Technical Communication UK 2017

The Technical Communication UK (www.technicalcommunicationuk.com) 2017 conference was in Nottingham, 26-28 September. Mike Unwalla gives this summary.

The presentation slides are on http://technicalcommunicationuk.com/?page_id=7663.

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:

Although you can do topic-based authoring with Microsoft Word, Microsoft Word is more like topic-based saving. [Ictect (http://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:

Usually, an organization has much old content. Before you buy new software for topic-based authoring, do a content audit:

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:

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:

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 invited 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.

Text that has a black mark over words that a user does not know.

A good method to find difficult text is to identify the 'circle words'. Three methods to find 'circle words' are as follows:

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:

Verint uses Jenkins (https://jenkins.io) for these tasks:

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:

Graeme summarized his presentation:

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:

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:

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" (http://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.

A technical writer must not assume. 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:

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:

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:

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:

Mobile learning is available on many types of device.

People incorrectly think that mobile learning is:

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:

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.de)

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:

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:

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:

Creating content and output for mobile and embedded devices

Speaker: Phil Lane, Imprimatur (www.imprimatur.co.uk)

Mobile content is all the types of content that is on a mobile device.

Users are in 2 categories:

An organization can supply content with these methods:

The user experience (UX) includes these properties 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 (http://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 existing tools. 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:

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