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:

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:

A document can be evaluated in approximately 0.5 day.

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

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:

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:

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:

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:

  1. Specify the scope. Identify the audience.
  2. 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.
  3. Create personas.
  4. 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:

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:

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:

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:

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:

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:

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:

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:

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:

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 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:

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:

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):

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:

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