Technical Communication UK 2010

The Technical Communication UK (https://istc.org.uk/tcuk) 2010 conference was in Oxford, 21-23 September. Mike Unwalla reports on the presentations that he attended.

Keynote presentation

Nokia (www.nokia.com) is a large company. Each day, 120,000 employees make 1.2 million mobile phones. Nokia spends 17% of revenue on research and development.

David Black explained how DITA is used to create documentation for the Symbian operating system. (In 2009, Nokia acquired Symbian Software. In 2008, David explained how technical authors were recruited to develop documentation for the Symbian operating system.)

At Nokia, the documentation team for the Symbian operating system has 45 technical writers and 15 other people. The Symbian operating system is one of four operating systems for mobile devices. The documentation team for Symbian operating system uses agile methods. The documentation team is in eight locations around the world. Many technical writers are in China and in India. The cost of technical writers is ¼ of the cost of technical writers in the UK. However, the transfer of skills can take many years.

The documentation team uses DITA because DITA is the only standard that everyone agrees on. Sometimes, the costs of DITA are more than the benefits. A large investment was necessary for the information architecture.

Nokia tried to use wikis for some content. But, many problems occurred:

• 78% of wikis contain some content that is in other wikis.
• 93% of wikis are not maintained after 6 weeks.
• 98% of wikis are not maintained for more than 6 months.

Some challenges of software documentation are as follows:

• Software constantly becomes more complex.
• Software constantly changes. Software development is very fast.
• Technical writing is becoming a commodity service.
• Large systems are more complex than one person can understand.

David ended with some advice for technical writers. In the future, documentation of user interfaces will become less necessary. Therefore, successful technical writers will be very technical. Average 'technical' authors will not be necessary. Where both complex systems and failure exist, high-paid work exists. A 0.1% decrease in defects pays for the cost of David's documentation department.

The spork/platypus average: content strategy at Red Gate Software

Content is everything that you give to a user. For content to be effective, you need a strategy. In simple terms, "make sure that your content does not suck".

A platypus is a marvellous animal. For example, a platypus uses electro-location to find objects (www.nature.com/articles/319401a0.

A spork is a combination of a spoon and a fork (https://en.wikipedia.org/wiki/Spork).

Roger thinks that both a platypus and a spork are useless, although a platypus is a marvellous animal. Effective documentation must not be like a platypus or like a spork.

"Nobody reads the manual" is a false statement. The truth is that "nobody wants to spend an hour reading the manual".

For a review of technical communications, ask the questions that follow:

• What documentation do we have?
• What documentation do we need?

Red Gate Software (www.red-gate.com) has free downloads. After someone evaluates the software, they usually buy the software. Usability testing shows that people who cannot find necessary information stop the evaluation. Too much information was only 'fluff'. Sufficient good-quality content was not available.

SQL Compare is the primary product from Red Gate Software. The website contained 158 pages about SQL Compare. The documentation team needed to know what content to keep, and what content to delete.

The primary question to ask is, "what is it for?" The documentation team made a list of the website content. Sometimes, the owner of each web page was unknown. Approximately 65% of the content was not necessary.

Roger said that technical communicators are 'content strategists'.

Terminology - who cares?

Each year, Lloyd International Translation (LIT, www.welocalize.com) translates approximately 30 million words. Terminology management is a large problem for LIT's customers. Jill Fifoot explained some of the problems, and gave some answers.

Terms that do not agree confuse both customers and translators. Jill gave two examples from electrical engineering:

• asynchronous motor = induction motor
• discrete input = logical input

Sometimes, one English word has many possible translations in a different language. For example, the English word 'valve' has the following French translations:

A customer must help a translator to know the correct translation.

Terminology management software helps to make terms consistent. Consistency has the benefits that follow:

• Consistency decreases the errors in the source and in the translation.
• Consistency increases the efficiency of translation.
• Consistency simplifies the review process.
• Consistency improves a customer's experience.

LIT surveyed approximately 200 international customers from different industries. Most source languages were English, French, and German. Terminology management was the largest problem for approximately 75% of the companies.

One customer said, "95% of translation issues are due to the way the text is written in the source."

Jill recommended the things that follow:

• Manage the terminology in the source document. Identify the most important terms for the business.
• Make terminology management part of the product development cycle.
• Involve all the departments.
• Start small.
• Agree the terms with the language service provider.
• Get management to agree to terminology management.

Everything you always wanted to know about psychology (and how it relates to technical communication)… but were afraid to ask

Chris Atherton (https://finiteattentionspan.wordpress.com) discussed the topic of 'user experience', and she gave many interesting examples. The presentation of data was only one of many topics.

To most people, the chart that follows is easy to understand. The bars are in the correct direction. A longer bar represents a higher value:

However, the chart that follows is difficult to understand. A longer bar represents a lower value:

A tree view is a good way to show the importance of data. The more important information is at the start of the hierarchy, and less important information is lower in the hierarchy:

Chris discussed Neuro-linguistic programming (NLP).

Before the conference, I asked Chris the following question:

"Practitioners of NLP say that different people have different learning preferences. For example, some people are 'visual', and other people are 'auditory'. Therefore, when you write or speak to a mixed group of people, use a mix of words. For example, different questions to get feedback on someone's attitude are as follows:

• "Do you see the picture?" [Visual]
• "Does that sound right to you?" [Auditory]
• "How do you feel about that?" [Kinaesthetic]

If NLP is correct that people prefer different terms, how do technical writers find a solution to the conflict between using different terms to engage different readers and using one term for one thing? (Most technical writers agree that 'one term for one thing' is good. To conform to some specifications such as ASD-STE100 (www.asd-ste100.org), a writer must use each term consistently.)"

Chris said that although someone says, "I am a visual person", no evidence supports the claim that 'visual' words will help that person to learn better."

Write more, write less: embracing the value of crafted words and images

Frequently, I tell my customers that they do not need to document all parts of their software. I was pleased to hear Joe Welinske of WritersUA says the same thing. Technical writers do not need to document all features of software. For the features that are documented, technical writers do not need to do the same quantity of work for each feature.

Joe says, "User assistance will become more effective when we spend twice as much time writing half as many words".

Put more work for important topics. Make sure that each word is useful. Decrease the quantity of text as much as possible. Although this work costs money initially, much money will be saved later in the project. For example, there will be fewer words to translate.

Chaos theory (reversed) — getting your act together

The documentation team at Micro Focus (www.microfocus.com) has 25 technical writers. Chris Hadley is the Director of Customer Care. He explained the requirements of his work:

• Customers want help to do their jobs.
• Management wants more output with less input, and they want it faster.
• The documentation team wants to be happy, and to make a difference to customers.

In 2007, Micro Focus acquired two companies. Therefore, Micro Focus had many different ways to create documentation.

To improve the documentation process, the documentation team decreased the number of authoring tools that they used. Now the team uses XMetaL and DITA. Some technical writers wanted DITA, but others were against DITA. Although the documentation team has too much work, the team has a good basis for future work.

Many people say, "nobody reads documentation". Chris said that if you remove documentation from a website, customers complain. These complaints show that people read documentation.

Keynote presentation: The Yellow Brick Road to effective content strategy

The world is very complex. In 2000, approximately ⅔ of CRM projects failed. Julian Murfitt of Mekon (https://mekon.com) used analogies with the Yellow Brick Road (https://en.wikipedia.org/wiki/Yellow_brick_road) to show the problems of content strategy.

For a content strategy to be successful, find the problems that a company has.

Julian gave an example of how a change in documentation saved money. The RAF had a fixed-cost contract with a supplier to keep Tornado aircraft airworthy.

The documentation explained that a particular part needed to be replaced when the part became worn. Because the documentation was text, the engineers were not sure when to replace the part. To be safe, the engineers replaced the parts more frequently than necessary. The documentation was changed from text to pictures. The engineers could easily see when a part needed to be replaced. The new documentation saved the company many thousands of pounds each year.

Julian said that to have an effective content strategy, technical communicators must do the things that follow:

• Be clear about the objectives.
• Find the problems and measure the problems.
• To get money for the content strategy, show how the objectives solve the problems.
• Involve all the members of the team.
• Measure the results.

Technical communication and inclusion

The Web Content Accessibility Guidelines (WCAG) 2.0 (www.w3.org/TR/WCAG20/) show that accessible web pages have the following properties:

• Perceivable. People must perceive documentation before they can use documentation.
• Operable. Documentation must not prevent people from using the documentation. For example, if text is in an image, and if the image does not have alternative text, blind people cannot access the information.
• Understandable. Unclear documentation is not accessible. Therefore, always use plain language.
• Robust. Different people access content in different ways. For example, some people want to use screen readers.

Similarly, to be accessible, documentation must be perceivable, operable, understandable, and robust. Karen Mardahl showed some simple methods to make documentation accessible:

• Accessible PDF files. For example, use plain language and use alternative text for images.
• Accessible videos. For example, include a transcript with a video. The transcript is a text version of the words that people say. If applicable, include information about actions. Transcripts are useful for people who can hear, because transcripts let people search for information. Additionally, search engines can index the information.

One person in the audience said that transcripts are useful for people who do not know English well. People can read the text instead of listening to an unusual pronunciation.

Adobe Acrobat contains an accessibility checker for PDF files. The accessibility checker finds problems such as images that do not have alternative text.

Karen's presentation slides are on www.mardahl.dk/2010/10/03/technical-communication-and-inclusion/.

Cultural awareness in technical communication

Culture includes things such as language, food, religion, and emotions. Glyn Turk works for an international company that has 4,500 employees. Glyn gave amusing examples of the problems that different cultures can cause.

In many countries, the weekend is Saturday and Sunday. However, in some countries, the weekend is Friday and Saturday. Therefore, do not say that you will do something by the weekend. Instead, specify the day.

In the UK, when people send e-mail messages, they do not think about the sequence of the names. However, in some cultures, hierarchy is important. The name of the most senior person must come first.

In one e-mail, someone from the UK wrote, "Now that we have started the project in anger…" American and Israeli colleagues were confused. They did not know the meaning of the idiom 'in anger'.

Some guidelines about how to minimize problems include the things that follow:

• Look for non-verbal signs of confusion.
• Be careful if you use humour.
• Do not use unnecessary body language. For example, do not use a 'thumbs up' sign, because in some cultures, the sign is not polite.
• Do not use idioms or slang.

"Just put it online as training" - project planning for e-learning success

Tina Hoffman explained that usually, the Edgecam software (www.edgecam.com) is sold with instructor-led training. Some simple 'getting started' tutorials were available.

An original-equipment manufacturer (OEM) used the software. There was no training and no support for the software. Therefore, the documentation team needed to supply some type of support.

Some advantages of e-learning are as follows:

• Learners can do the training when they want to.
• Support costs are decreased.
• Training is internationally available.
• Training is standard and consistent.
• Training can be monitored.

Some disadvantages of e-learning are as follows:

• Learners need self-discipline.
• People like to speak, which is difficult with e-learning, but easy in a classroom.

The documentation team had the following problems:

• E-learning is more difficult to create than a demonstration video.
• Some learners are beginners and some learners are subject-matter experts.
• Some learners want printed documents.

Design e-learning so that learners can learn easily:

• Emphasize what you want to teach.
• Prevent visual clutter.
• Make sure that content is easy to read. Keep text short.
• Put the content into context.

Using graphical illustrations in software documentation

Martin Block gave many examples of how to use graphics in software documentation.

A graphic can show much information quickly, but sometimes, graphics have problems:

• Graphics can take much time to create.
• Graphics can make a document long, and can make the file size large.
• Graphics can be unnecessary.

Martin's presentation was visual. Because the content will appear in Communicator (https://istc.org.uk/homepage/publications-and-resources/communicator/), I do not give examples here.

Open session: questions and rants

In this session, 11 people spoke for 3 minutes each. My favourite topics are shown below:

• Colum McAndrew wanted to know why instructions for consumers are frequently very bad. For example, an instruction manual for a greenhouse includes the text, "this is a multi-part assembly".
• Westrow Cooper wanted to know why recruitment agencies focus on software tools, not on solving a customer's problem.
• Chris Atherton tried to teach the basic methods of statistical correlation.
• Graham Wignall spoke about Commoncraft (www.commoncraft.com). Commoncraft makes simple video explanations of complex information. Each video is approximately 3 minutes. Graham said that if a technical communicator cannot write a 3-minute script to explain a product, then the technical communicator will struggle to document the product.

Keynote presentation: Who are you communicating with?

The first Haynes manuals (www.haynes.com) were for people who repair cars. Manufacturers supplied manuals, but the manuals were for professional mechanics, not for amateurs. J Haynes explained how clear documents made Haynes a successful company.

Although Haynes manuals were for amateurs, professional mechanics bought the manual. J Haynes explained that each manufacturer had different styles and layouts. Different manufacturers had different sequences of operations. Haynes manuals for different cars all had the same style and layout. Professional mechanics could easily find the information that they needed.

Sometimes, Haynes made mistakes. For example, when Haynes entered the French market, Haynes did not understand the audience. There were two primary problems:

• French people think that hardback books belong in libraries, not in workshops.
• French people cannot easily say 'Haynes'.

Now, Haynes writes manuals for many things. For example, there are manuals for musical instruments, for animals, and for Thomas the Tank Engine (https://haynes.com/en-gb/microsites/thomas).

© TechScribe, Sheffield, South Yorkshire. Page updated 2010-10-04