Technical Communication UK 2017
The Technical Communication UK (https://istc.org.uk/tcuk) 2017 conference was in Nottingham, 26-28 September. Mike Unwalla gives this summary.
Topic-based authoring—is it for me?
Speaker: Mike Hamilton, MadCap Software (www.madcapsoftware.com)
Mike told a good story. He was a technical publications manager in the nuclear industry. He changed to the semiconductor industry. Blue Sky Software Corporation, which supplied RoboHelp, asked him to join the organization. A company bought Blue Sky Software Corporation, and Mike was fired. He started MadCap Software, which sells the MadCap range of software for content development.
When Mike uses the term single-source publishing, he means a process that has these features:
- A document workflow
- The content is in only one location. There are no copies of the source content.
- The supply to the user is 'flexible'.
Although you can do topic-based authoring with Microsoft Word, Microsoft Word is more like topic-based saving. [Ictect (www.ictect.com) was at TCUK 2017. The Ictect software operates with Microsoft Word and lets you write DITA or change content to DITA.]
Do not use topic-based authoring because it is 'cool' or because other organizations use it. Use topic-based authoring if it adds value. "For some companies, a linear workflow is fine."
Topic-based authoring has these benefits:
- The content has only one source. There are no copies of source files.
- The published content can be in many formats.
- The audience has only the applicable content.
- The process has increased automation.
Usually, an organization has much old content. Before you buy new software for topic-based authoring, do a content audit:
- What is the quality of the content? (Content that has bad formatting will cause problems when you import it into the software.)
- Is the content active or is it not used?
A topic is a unit of information that answers a question. For example, one topic is about how to remove a discharged battery and contains a procedure 'to remove a discharged battery'. A different topic is about how to install a new battery. Usually, if you maintain an item of equipment, immediately after you remove a discharged battery, you install a new battery. In practice, the 2 procedures can be in the same topic.
Do not do these things:
- Train all the technical communicators in your team to do all the tasks in the content workflow. Use a 'divide and conquer' method.
- Use the vendor's templates. People in your organization must decide the types of topic and then develop a template for each type of topic.
- Use the old method and the new method at the same time.
- Do the work without a style guide.
- Start the project if people in other departments such as IT, the website team, and the marketing team do not agree with the project.
Work smarter, not harder
Speaker: Wayne Brissette, Arm (www.arm.com)
Arm has 6 teams of writers in France, the UK, and the USA.
In 2011, Wayne's team started to use DITA. Wayne spoke about the problems that the team had.
The team documented 8 processors. Each processor has many 'IP blocks'. Each processor has a different release date. To solve this problem, the team looked for general topics that they can share. They used variables as much as possible in the documentation and they wrote general text as much as possible. If the name of a product was not necessary, they did not use the name in the documentation.
Technical experts (subject-matter expert) do not always agree. The technical communicators were the 'traffic cops', because they had the authority to decide about the content.
DITA has many methods to get the same result. To solve this problem, the team used these methods:
- Automate if possible
- Standardize the format
- Let one person control all the processes in the projects.
To measure the quality of the documentation, the team had meetings to evaluate the quality. The technical experts made sure that the content was correct. All the information developers were asked to participate. During the sessions, people found text that does not make sense.
One method to measure productivity is that all the targets are met. A different method is that the information developers do not think that they have too much work.
One person asked about how to measure the quality of the content. Wayne told us that Arm uses Acrolinx. A different person added that Acrolinx and other software can only find errors with text. They cannot find technical errors.
Wayne ended the presentation with the words, "You work too hard. Make the tools work for you."
Jargon and the curse of knowledge
Speaker: Frances Gordon, Simplified (www.simplifiedcommunication.co.uk)
Plain language experts and technical communicators are separated. They do not communicate. But, they have much to learn from each other.
Frances said that jargon is "a type of language that is used in a particular context and may not be understood outside of the context." Jargon is a shortcut, but it becomes a barrier. Jargon is also known as 'terms of art', specially in the legal profession.
Most people prefer plain English (https://gds.blog.gov.uk/2014/02/17/guest-post-clarity-is-king-the-evidence-that-reveals-the-desperate-need-to-re-think-the-way-we-write/).
Stephen Pinker writes, "The curse of knowledge is the single best explanation I know of why good people write bad prose. It simply doesn't occur to the writer that her readers don't know what she knows." [The Sense of Style, 2014, page 61.]
Frances gave some methods to simplify text.
A good method to find difficult text is to identify the 'circle words'. Three methods to find 'circle words' are as follows:
- In a text, put a black mark over all the words that you think the audience will not understand. This is not a good method, because of the 'curse of knowledge'.
- Do a user test to find the circle words. This is a good method.
- Do a corpus analysis to find how frequently the words occur in English. If a word occurs frequently, most readers will probably understand the word.
After you find the circle words, use a 'drafting checklist' to decide whether to replace each word or to use it and write a definition:
Is the word in general use? If yes, use the word. If no, does the word have a technical meaning? If no, replace the word. If yes, can you replace the text with a shorter or easier alternative? If yes, replace the text. If no, keep the jargon and write a definition of the term.
Frequently, you can remove unnecessary words and phrases to make text simpler. "I, the undersigned, do hereby revoke, cancel, and annul…" means "I cancel…"
A definition has 4 parts:
Use only one sentence for each definition, and write the special properties of the item that you define. Do not define a term with the term. Do not write that something is not X. Frances said not to include examples and explanations, but I think that examples are good. Holli Hamilton includes examples in glossaries.
The special properties are dependent on the context. Think about this definition: A robin is a type of bird that has a red breast. In a book for young children, the definition is. In a book for experts, the definition is bad.
As a test of a definition, replace the text with the definition. The text must make sense.
Resistance is futile! How automation can improve your docs and your life
Speaker: Graeme West, Verint (www.verint.com)
Although automation and artificial intelligence are risks to technical communicators, Graeme thinks that we can have interesting careers in which we do many tasks. Writing will be only a small part of our work.
In 2016, Graeme started to work at Verint. The documentation contained much inconsistent language.
To improve the quality of the documentation, Graeme started to use continuous integration (CI). Continuous integration is a method that is used in software development. Continuous integration makes the process simpler:
- There are no difficult build scripts.
- All tasks can be repeated.
- All the changes to the content have a record.
- Diagnosis of problems is easier than with other methods of documentation.
Verint uses Jenkins for these tasks:
- Web pages
- Acrolinx checks
- Find broken links. For example, Jenkins checks each build for broken internal links. Each week, there is a check for external broken links.
- Automatic syntax highlighting of code examples
- Feedback about the documentation
To use continuous integration, do an audit of the work processes. If a task is difficult or frequently causes errors, automate the task. Find manual processes that you can automate.
Three basic types of tools for continuous integration are available:
Continuous integration has some problems:
- Much time is necessary to automate all the build.
- Creating checks is not easy. Unlike software code, libraries are not available.
- Incorrect warnings (false positives) are more frequent with documentation than with code.
Graeme summarized his presentation:
- technical writers must adapt
- Continuous integration decreases the difficult and boring work.
- Continuous integration lets you try new methods.
- Time is necessary to start, but you will get a return on investment.
The glossary is dead! Long live the glossary!
Speaker: Holli Hamilton, Corero Network Security (www.corero.com)
In web-based help and on websites, there is usually a search box. But, there is no glossary.
In topic-based authoring, how can you be sure that the documentation contains all the necessary topics if there is no linear structure?
Holli looked at all the documentation to find possible terms for the glossary. To identify missing topics, she asked, "Do we have a concept topic for this term?"
When Holli started work at a new company, she used the glossary-based writing method that she developed.
First, find all the terms and write a glossary. Then, for each term, write a concept topic
Each topic has this structure:
The term
A definition and an example
Links to tasks
Conceptual information
Links to reference information.
In the content, include links for all the terms.
To decide which term must be in a glossary, use Wikipedia. If a possible term is on Wikipedia, and if the Wikipedia meaning is the same as the meaning of your term, do not include the term in your glossary.
Holli thinks that in many companies, people think that glossaries are not important. I agree. For many TechScribe projects, one of the first tasks is to get a list of technical terms and their meanings.
Optimizing API documentation: What we can learn from developers
Speaker: Stephanie Steinhardt, Merseburg University of Applied Science (www.hs-merseburg.de)
The usability of API documentation is becoming important. Frequently, API documentation is large. Do the software developers need all the information? Can they find the information that they need?
API documentation has more than one possible design layout. Are some layouts better than other layouts?
Stephanie and Michael Meng did some research to find answers to these questions:
- What do software developers expect from API documentation?
- How do software developers use API documentation?
The most important question from software developers is, "What can I do with this API?"
A question to software developers was about the steps they did when they learned a new API. Software developers use different methods, but usually, they try to use the API.
Sample code is very good, specially when a software developer starts to use an API.
The structure of the API documentation is important. It must let software developers quickly access the content.
The results of the research are only a start, and more research is necessary.
Why topic-based writing and plain language need each other
Speaker: Frances Gordon, Simplified (www.simplifiedcommunication.co.uk)
Much plain language work is done in the context of legal compliance.
Usually, plain language is measured with these methods:
- Readability. Readability is usually about sentences, not other features such as cohesion and structure, which make a document easy to read.
- Process analysis
- Outcomes analysis
English has many idioms. For example, the phrase right now means immediately, but readers in Nigeria probably do not understand the idiom.
Francis said that the best definition of plain language is from the Center for Plain Language. "A communication is in plain language if its wording, structure, and design are so clear that the intended readers can easily find what they need, understand what they find, and use that information" (https://centerforplainlanguage.org/learning-training/five-steps-plain-language/).
I think that the definition is not good, because it does not tell me what a document must contain or must not contain. It tells me about the functions of plain language.
The reuse of content is important.
When a person is stressed, the person can have a temporary decrease in literacy.
What I wish I'd known before doing user research for the first time
Speaker: Jen Lambourne, Government Digital Service (www.gov.uk/government/organisations/government-digital-service)
People need "the right content at the right time in the right context." To be sure that you give people the correct information, do user research.
Technical writers must not think that they know the users. We are not the users of the product and we do not know what they want. Without user research, we can create a product that people do not want, as the Juicero company did with its $400 juice press (https://en.wikipedia.org/wiki/Juicero).
A small quantity of research is better than no research.
Find what works, not what is popular. Do not compare you work with that of competitors.
You can do many types of user research:
- Interview the users. A problem is that much time is necessary.
- Look at the users.
- Test a prototype.
- Evaluate the content.
- Use heat mapping. The user highlights in green all the features that increase the user's confidence. The user highlights in red all the features that decrease the user's confidence.
- Rent space in a user-testing laboratory and do tests such as eye-tracking.
Do not try to get too many people and stagger the research. Much time is necessary for the analysis.
The Hawthorne effect shows that people behave differently when they know that they are watched (https://en.wikipedia.org/wiki/Hawthorne_effect).
After you complete the user research, do these tasks:
- Schedule the work and do the important tasks first.
- Write new user stories.
- Make the content better.
The GOV.UK Service Manual has a section about user research (https://www.gov.uk/service-manual/user-research).
The future of mobile learning
Speaker: Danielle M Villegas, Dair Communications (www.daircomm.com)
In past times, songs and stories helped people to remember. But, songs and stories are not always sufficient. When writing developed, people had a method to keep information permanently.
There are 3 types of learning:
- Spoken
- Paper
- Electronic
These 3 types of learning all support each other.
For instructional design, only a small quantity of information is necessary at a given time.
Some features of mobile learning are the same as the features of instructional design:
- Customized for each person who uses the product
- Immediately available
- Short.
Mobile learning is available on many types of device.
People incorrectly think that mobile learning is:
- The transfer of information to a small device
- Expensive
- Available only when a device has an internet connection.
Mobile learning is not always applicable. An effective mobile learning product must 'know' the context in which it is used.
To make mobile learning is not easy:
- Mobile learning is used on many different types of device.
- Mobile learning is used on small screens.
- People cannot easily enter text.
- Possibly, access to the internet is restricted.
Danielle ended her presentation by saying that the early practices of e-learning are applicable to mobile learning.
Industry 4.0 — and documentation 4.0
Speaker: Thomas Schubert, kothes (www.kothes.com)
Wikipedia tells me that "Industry 4.0 is a name for the current trend of automation and data exchange in manufacturing technologies" (https://en.wikipedia.org/wiki/Industry_4.0).
Thomas spoke about how real-time data improves the manufacturing industry.
A machine can supply information that a change of oil will be necessary in 3 days. Other information from the system can identify machines that will have spare capacity in the next 3 days. Thus, automatic scheduling of the oil change is possible.
For instructions about how to change oil, 2 basic options are possible:
- Supply documentation, usually as a PDF file
- Use augmented reality that is applicable to the machine.
The function of 'documentation 4.0' is to "close the user's knowledge gap as quickly as possible."
Before you can use documentation 4.0, you must know the company vision and the functions of the technical writers. You must do these tasks:
Typical tools to use are as follows:
- An XML content management system
- A content publishing platform
- A metadata classification tool.
Documentation 4.0 is a good solution for many documentation problems. Technical communicators can use Industry 4.0 to help the users.
Five Cascading Style Sheet techniques that every technical writer should know
Speaker: Mike Hamilton, MadCap Software (www.madcapsoftware.com)
A Cascading Style Sheet (CSS) controls the appearance of a markup language such as HTML.
Mike's presentation contained many examples of how to use CSS. He showed some advanced methods. Mike gave many examples, some of which are as follows:
- Change the size of an image, such that the image fits to the maximum width of the screen.
- Change the text that a user sees for different sizes of the screen. Examples:
For a mobile device: Please tap
For a desktop computer: Click here - Create a button without using an image.
- Show text or an image dependent on the condition of an item. (For example, when the pointer is over a link, the link text changes colour.)
- Automatically show an icon in front of a link. Icons can be different for links to different types of document (Word, PDF, zip).
Creating content and output for mobile and embedded devices
Speaker: Phil Lane, Imprimatur (https://imprimatur.co.uk)
Mobile content is all the types of content that is on a mobile device.
Users are in 2 categories:
- Known: these people are employees or external people who are trained to use your product.
- Unknown: a supplier does not always know all the people who use a product.
An organization can supply content with these methods:
- On a website
- As an app
- As embedded content in the product.
The user experience (UX) includes these properties of the content:
- The appearance
- Accessibility
- The flow of the content
- The design of the content.
The content must be short and for one purpose. Think "every page is page one".
Related content must be easy to find.
Minimalism is important, but "Minimalism is not a lack of something. It's simply the perfect amount of something" (http://nicholasburroughs.com/designschooldropout/quotes-perpetuate-thoughts-xvi/).
Video can be a good method to give information. For example, written instructions for crochet are not easy to understand. With videos, you can see what you must do.
Security is very important for mobile devices. Mobile devices are easily lost.
The encryption of information on websites is important. You can get a free encryption certificate for a website from Let's Encrypt (https://letsencrypt.org/).
Automatic documentation for software
Speaker: Andrew McFarland Campbell, Synchronoss Technologies (https://synchronoss.com/)
Automation is necessary because a product can have thousands of configurations.
The most difficult part of automation is that you must change how you think. You change from a technical writer to a software developer. You become an editor.
Automation is not good for some types of documentation such as concepts, but for reference information, it is very good.
When you automate, if possible, use standard solutions and the tools that you have. For example, if a project uses Java, then use Javadoc.
Possibly, custom solutions are necessary. For example, you can get data from a configuration file and change it to DocBook.
Automation has some possible problems:
- Automation adds complexity.
- Automation makes the accidental publishing of private information very easy. For example, if software has a switch that is only for people in the support team, you do not want the documentation to be public.
- The technical writers must have programming skills.
- The software developers must have technical writing skills.
As with most projects, the most difficult parts are not the technical parts. You must get support from the management team, and you must change how people think.
RSS feed