Technical Communication UK 2011

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

Using the tech author slide rule: measuring and improving your documentation quality

Speaker: Alice Jane Emanuel,Comma Theory.

Dictionaries identify 'quality' as 'the degree of excellence'. However, what does 'excellent' mean? You need to know what the readers need and what the readers do not need. Only then can you evaluate quality.

Quality is dependent on many things. Some examples follow:

The audience
The function of the documentation
The resources (money, equipment, time)
Corporate guidelines such as brand design and colours.

Peer review is one way to evaluate quality. To make peer review easier, Alice Jane created a spreadsheet. To evaluate a set of documents, first specify the importance of each item that will be evaluated. Next, evaluate each item.

To specify a weight, you need to know what is important to a customer.

Some general categories in the spreadsheet are as follows:

Document structure
Cross-references and navigation
Graphics
Terminology.

A document can be evaluated in approximately 0.5 day.

The spreadsheet helps in many ways. Some examples are shown below:

Show the relation between an improvement in a document and the sales of a product.
Help to train new technical writers.
Help to make the documentation 'localization ready'.

Statistics without maths: acquiring, visualising and interpreting your data

Speakers: Chris Atherton, Finite Attention (https://finiteattentionspan.wordpress.com); Karen Mardahl (www.mardahl.dk); Mike K Smith, Pfizer (www.pfizer.com).

Statistics helps people to change information into knowledge. Two things are very important:

Evidence must be strong
The quality of data must be good.

How we ask a question is important. Chris asked the question, "Do you like Revels?" Fifteen out of 28 people lifted their hands.

Chris gave the people at the back of the room one Revel each.

Revels have different flavours. Chris asked, "Do you like the Revel that you were given?" Six out of 11 people liked the Revel that they were given.

This small example shows typical problems with statistics:

Only people at the back of the room got a Revel. Do these people represent all people in the room?
Revels have different flavours. Each person had only one flavour from many.
The question, "Do you like Revels?" is different to "Do you like the Revel you were given?" We must ask what we mean.

For an amusing perspective about correlation, Chris showed https://xkcd.com/552/.

For more information about Chris' presentation, see the 'Stats Without Maths Goodie Bag'.

Make icons make sense: solving symbols for global audiences

Speaker: Patrick Hofmann, Google (www.google.com).

To write well, a technical writer needs to know the audience. Patrick explained that similarly, when graphic designers create icons, the graphic designers must know the audience.

Context helps to give meaning to an icon. For example, think about the following icon:

A black cross

Meaning is dependent on context. Without knowing the context, you cannot know which of the following things the cross represents:

A cross on a bottle of medicine
An 'Add' button on a calculator.

To create a good icon, simplify the icon as much as possible. Do not include unnecessary detail. The clearest icons represent nouns without related adjectives. For example, if an icon represents a man, then the man is not young or old. People cannot say, "This icon represents an old man."

Making icons for international use is difficult. The alternative to internationalization is localization. However, localization increases the cost of a product.

Sometimes, people must learn the meaning of a new icon, because the meaning of the icon is not clear. In this situation, the best option is to include a label with the icon.

For more information, Patrick recommended the following websites:

Focus on the user, the rest follows

Speaker: Joanne Lasselle, Laselle-Ramsay.

The primary function of technical documentation is to improve the performance of users.

To help users, you must know about the requirements of the users.

Joanne recommended the following strategy:

Specify the scope. Identify the audience.
Collect and analyse data. Who are the users? What do the users do? Identify tasks and the frequency of tasks. Learn about the work conditions.
Create personas.
Specify the information that each persona needs. Specify the overlaps between personas.

A useful method to learn about users is to create user stories. A user story has the following structure:

As a <job role>, I need to <do something> because <reason>.

Joanne gave the following example:

As a customer support engineer, I need to find information quickly, because time is money and waiting makes customers irritated.

Content strategy year 1: a tale from the trenches

Speakers: C J Walker, Firehead (https://firehead.net/); Karen Mardahl (www.mardahl.dk).

This presentation was unusual, because C J Walker interviewed Karen.

Karen writes user manuals about microphones for G.R.A.S. Sound & Vibration (www.grasacoustics.com). Although the company is in Denmark, the documentation is in English. Before Karen worked at the company, the company did not have a technical communicator for some years.

Karen's colleagues do not know terms such as 'technical communication' and 'usability'. Therefore, Karen explains her work to her colleagues.

Resources are restricted. Information is not always complete, but Karen says that she is not afraid to publish information that is not complete.

To evaluate success, Karen is creating metrics.

Why and how service information is critical to your business

Speaker: Peter Li, Simonsoft.

Peter defines 'service information' as 'all the information that people need to use a product'.

Businesses want to do many things with restricted resources. Peter used the idiom, "do not put lipstick on the pig." Instead, use the resources that are in the organization. Good service information can help an organization to use those resources.

If service information is not easily available, service engineers waste much time searching for that information. Large companies have many thousands of service engineers. If the service engineers can find information quickly, a company can save much money.

In many companies, people in the engineering department and the service department do not communicate. The lack of communication can cost a company much money.

To solve the problem, people, processes, and technology are all important. A graphic compared the 'maturity' of documentation with effectiveness of the documentation:

The effectiveness of information increases in proportion to the the maturity of the delivery method.

I do not agree that an interactive document is always better than a non-interactive document. The effectiveness of a document is dependent on the requirements of the users.

Peter gave an interesting demonstration of an interactive electronic technical manual (IETM). Peter showed how a user can click a part of a machine to 'drill down' to a component. At the lowest level, information about a component is shown. In some IETMs, a user can order new parts or see information about installation and repair.

Good service information decreases the time that service engineers need to find information. Therefore, repair times are decreased.

How to be a riveting speaker

Speaker: Andrew Lightheart.

Andrew explained how to be a good speaker. Andrew recommended the following things:

Speak slowly. Andrew has helped more than 4000 technical people to improve their speaking skills. Andrew never told someone to speak more quickly.
Do not give a presentation. Instead, speak to people.
Have good information. Think about what you want people to do at the end.
Tell stories.
If necessary, use notes to help you to remember what to say. Public speaking is not the same as acting.
For the first 15% to 20%, do not speak about the topic. Instead, make people interested. Show how listening to the presentation will be a benefit to the listener.
Do not be afraid of silence.

Developing user documentation in an agile environment–an international standard

Speaker: Cerys Willoughby (www.linkedin.com/in/cerys).

Cerys represents the UK on international standards for software and systems documentation.

The current international standards for software documentation do not have information about agile software development.

For technical writers, two important effects of agile software development are as follows:

Technical writers create only what users need.
Frequently, technical writers must change what they wrote, because the requirements change.

Cerys explained how the ISO working group develops standards. (Read TechScribe's explanation in 'The development of ISO/IEC 18019:2004'.)

The IKEA concept: global and 'textless' communication, a pedagogical challenge

Speakers: Jan Fredlund, Magnus Ohlsson, IKEA (www.ikea.com).

IKEA makes flat-pack furniture. Most people in the room have visited an IKEA store. Jan and Magnus explained how IKEA creates its assembly instructions.

The IKEA business idea is "to offer a wide range of well-designed and functional life-at-home products with such a low price that as many people as possible can afford them."

IKEA continuously tries to minimize costs. IKEA's customers help to minimize costs. Customers do the following things:

Buy products without the help of a sales person.
Bring products to the cashier.
Bring products to their houses.
Assemble products.

Text is expensive to translate. Therefore, if possible, IKEA uses graphics for assembly instructions. All the assembly instructions are tested to make sure that people can use the assembly instructions.

Each year, 20 technical communicators create approximately 400 assembly instructions. Additionally, each year the technical communicators change approximately 400 assembly instructions.

The design guidelines for assembly instructions are as follows:

Tell a story.
Use a simple design. For example, use graphics that have only lines. Do not use photographs.
Let customers have an early and easy success. For example, show something that is easy to understand and easy to do.
Use detailed instructions. Make sure that each instruction continues from the instruction that comes before it.
Make sure that the assembly instructions are possible to do. For example, the following graphic shows something that is not possible:
Know the limits. If necessary, use text.
Emphasize possible problems.

In the future, IKEA will possibly use animated instructions. Now, animated instructions are not practical, because many customers do not have access to the applicable technology.

People asked many questions. The answers were interesting:

The largest set of assembly instructions contains 60 pages of instructions in 4 different configurations.
One woman in Jan's team chooses the names for products. Frequently, names are boys' names and Norwegian lakes.
The designs for products are Scandinavian. IKEA does not change the design for different locations.

Can't see the wood for the trees: an introduction to documentation audits

Speaker: Tina Hoffman, Planit Group.

Tina is a technical communicator at the Planit Group. Because of many mergers and acquisitions, the documentation team did not know what documents they had.

For the following reasons, the documentation team needed to know what documents they had:

To avoid having many copies of the same document
To increase the effectiveness of the documentation
To use single-sourcing.

When Tina tried to find the information about the documents, some people did not give help. For example, some people said "who are you?" and "why are you asking me all these questions?"

Strangely, some people did not know that they write documentation. For example, in one office, people wrote installation documents. However, when Tina asked them whether they write technical documents, they said no.

A documentation audit answers the following questions:

What documents do we have?
In what formats are the documents?
Who writes the documents?
Who uses the documents?
What is the document life cycle?
How easily can people find the documents?

Initially, start with a small documentation audit. For example, do a documentation audit for only one product or only one department.

A documentation audit finds all the applicable documents. Instead of a documentation audit, possibly a survey is sufficient. In a survey, you do not try to find all the applicable documents. Instead, you find a representative sample.

For a documentation audit to be useful, an organization must do something with the results of the documentation audit. Therefore, at the end of the documentation audit, do the following things:

Write a summary of the documentation audit.
Verify the results with some of the people who supplied data for the documentation audit.
Recommend the best options to the management.
Design a content strategy.

Machine translation–yes or no?

Speaker: Tom Gannon, Welocalize (www.welocalize.com).

Machine translation is not as good as human translation. Machine translation gives many errors.

When machine translation was initially developed, many problems were caused because words can be ambiguous. In the 1990s, the power of computers increased, and machine translation gave better results.

To know whether machine translation is satisfactory, an organization must answer many questions. Some examples follow:

Do the stakeholders understand the benefits and the problems of machine translation?
Must the organization decrease costs immediately or in the future?
Does the organization have more than 1 million words of source text and translated text?
Is the translated text 'clean' and consistent?
Is the translated text in a translation memory system?
Will the translations be for use by people in the organization or for external use?
Is the content sales and marketing literature?

Machine translation that is not customized has the language ability of a child of 10. A child of 10 can write, but a child of 10 struggles with complex content. However, machine translation software can be trained to give better results.

The quality of translation is dependent on 3 things:

The complexity of each sentence.
The proportion of words that are used in an unusual way.
The importance of a literal translation.

The best way to train machine translation software is with a small domain. Google Translate is trained on a large domain. Therefore, Google Translate can say a little about much. However, Microsoft's machine translation software is trained with Microsoft's content. Therefore, the machine translations are good.

To decide whether training is successful, evaluate the translations:

Automatic evaluation. Automatic evaluation compares the translation with a reference. The result does not always show the accuracy of the translation. For example, if the translation contains an incorrectly inserted 'not', the result can be good, but the meaning is not correct. The best use of automatic evaluation is to measure the improvement in training.
Manual evaluation. Evaluation by people is necessary. However, human evaluation is expensive, inconsistent, subjective, and needs much time.

If necessary, a machine translation can be improved by post-editing.

Human translators can translate approximately 2000 words a day. With machine translation and post-editing, 3000 to 9000 words a day can be translated. The amount of post-editing that is necessary is dependent on the quality of the source text. Sometimes, machine translation is very bad and post-editing is not practical. Instead, a translator must translate the text again.

Machine translation does not replace human translation. Instead, machine translation is a tool. Only some types of document are suitable for machine translation. For example, 'creative' documents are not suitable for machine translation.

Some suppliers of machine translation software say that organizations can save between 40% and 500% compared to human translation. Tom says that these numbers are not correct. Microsoft has a 17% cost saving by using machine translation.

Each year, the amount of translation increases, but budgets do not increase. Therefore, machine translation will be used more frequently.

Agile in practice: panel discussion

Speakers: Rachel Potts, 3di Information Solutions (https://3di-info.com); Roger Hart, Red Gate Software (www.red-gate.com); Cerys Willoughby (www.linkedin.com/in/cerys); Sherryl Abrahart, E-How.

The idea of this presentation was to share experiences of working with methods of agile software development.

The waterfall method of software development is linear: requirements → design → develop → test → document → release. Testing and development are repeated until there are not many errors.

A large problem of the waterfall method is the large amount of time that is necessary before a product is released. The function of agile software development is to give users a product in a short time. After the product is released, new features can be added.

Agile software development has an effect on the work that technical communicators do.

Roger said that the largest cause of failure with agile software development is 'scope creep'.

David Farbey made an interesting comment. The problem is not Scrum. The problem is Scrum that is done badly and with interference from management.

Sherryl said that the use of agile methods makes a technical communicator think about what is important. But, sometimes, technical communicators do not know about features until the features are complete.

Some technical communicators and managers think that agile software development is good, but other technical communicators do not agree.

Write less–say more. The added value of minimalism

Speaker: Jan Graat, JANG Communication (www.jang.nl).

A large problem with complex documents is that information is available, but people cannot find that information.

Effective documents maximize the 'signal-to-noise ratio'.

A minimalist document minimizes the following things:

The cost of translation
The cost of paper, if the document is printed
The work that a reader must do.

A problem is how to give the users the information that they need. One option is to put tutorial information in a PDF file, and supply detailed information as context-sensitive help. TechScribe agrees.

To maximize the clarity of a document, each topic must answer only one question. The order of importance for questions is as follows (most important first):

How do I do this?
What went wrong?
How do I use this option?
How does this thing work?

Consistency is important. Some technical writers want to be creative, but inconsistency can cause problems for readers.

To remove ambiguous text, use a controlled language. All the following words have approximately the same meaning:

Bewildered
Confused
Disoriented
Unclear
Unsure.

With a controlled language, a technical writer uses only one of those words.

Minimalism helps to improve safety. Warnings are useful, but if a document has too many warnings, then possibly, readers will ignore the warnings.

One interesting question was, "where does minimalism fail?" Jan said that minimalism never fails. TechScribe agrees.

The changing role of technical communicators

Speaker: Ellis Pratt, Cherryleaf (www.cherryleaf.com).

Ellis gave information about the need for technical communicators and the wages of technical communicators. The numbers were from www.itjobswatch.co.uk. Cherryleaf did a survey of technical communicators, and the other numbers that Ellis gave were from the Cherryleaf survey.

As a proportion of all jobs, technical authoring decreased between 2004 and 2011. However, companies want technical authors who have expert knowledge.

To find information, many people search the Internet. However, only 21% of technical communicators create content that can be found on the Internet.

The 2 most popular search sites are Google and YouTube. However, most technical communicators do not create video content.

The value of documentation is not measured. Only 7% of technical communicators measured the value of documentation. Only 10% of technical communicators know whether users read the documentation.

Changes in technology have a large effect on technical documentation. In the 1980s, people needed technical documentation to use large systems. If a large system is not used correctly, possibly, much damage will occur. Now, much technology is simple and small. Possibly, people do not need documentation.

Some technical communicators use structured writing. However, other technical communicators do not like structured writing. A conflict exists between engineering and art. Possibly, the unsatisfactory appearance of some types of documents and the large cost of establishing a system are reasons why structured writing is not popular.

Many technical communicators are moderately old. To be successful in the future, the technical communication profession must attract younger people.

RSS feed