How to write a user manual

1. Underestimating the importance of the user manual

The most common mistake made when writing a user manual or a use and maintenance manual has less to do with content, and more with approach. Some will say this is a nuisance, because it means extra work and costs, and some will call it unnecessary “no one reads it anyway”.

But just how justified are these attitudes?

Well, it’s true that writing an owner’s manuals takes time and resources, and it’s also true that users don’t always read instructions from beginning to end. It must be remembered, however, that according to Directive 2006/42/EC, also known as the "Machinery Directive," the manual is an integral part of the product and not an optional or accessory component. It’s a legal requirement.

Legal requirements should not, however, be the only reason for a company to care about a manual’s content that accompanies its products.

If the information and the instructions are clearly and comprehensively communicated, there will be fewer complaints and support requests, and it will also reduce risk to users, damages and product malfunction. This also leads to fewer costs for customer service, replacements, and field services.

2. Using unnecessarily complex language

One of the most common issues concerns the choice of words and terms. But what is the difference between the two? Words belong to the common lexicon, vocabulary we all use, while terms belong to a specialised lexicon which is unique to a product and to the sector it belongs to.

The most common mistake is to think that if the subject is complex, simple expressions just won’t be adequate. On the contrary, it is precisely the fact that manuals often deal with complicated subjects that it is important to use language that everyone can understand.

Though it may seem obvious, a Basic Vocabulary that collects the words most widely used and understood by a majority of speakers can be a useful resource in this sense.

For example, rather than “refresh”, which is not included in this vocabulary, you could use “reload”.

As well as words from higher registers, we also tend to use a lot of fixed expressions. “Drill a hole” or “make a cut” could be replaced with “drill” and “cut”, which are shorter and more direct.

And how should I handle terminology?

First of all you, need to ask yourself who the manual is intended for. Are you targeting an experienced user such as an installer, or a general user? In this case, term meanings should be explained. To help less experienced users, you could create a glossary, i.e. a list of explained terms.

The glossary can range from a simple collection of terms accompanied by a brief definition, to a full-fledged terminology database, in which each concept is explained, illustrated with drawings or photographs, and possibly translated into all necessary languages.

3. Using unnecessary synonyms

Contrary to what you might think, and to what we were taught in school, using synonyms is a mistake here, and of the most common ones. “Device”, “tool”, “appliance” and “machine”, or “key” and “button” are often used to avoid repetition.

While these synonyms might help enrich a blog post or an essay, in technical documents, they just cause confusion. If the instructions talk about an “allen key”, this needs to be called an “allen key” consistently throughout the entire document, and not “allen” in one sentence and “hex” in another, as the user may not understand what is being referred to.

Let’s take these sentences as an example:

In just two lines, the writer has used “life jacket”, “safety vest”, and “pfd”: three ways to refer to the same product. When there are multiple terms to refer to an object, even when they are all correct, you will need to settle for one and continue using this one term throughout the entire text.

4. Using industry-specific jargon or unexplained technical abbreviations.

Another mistake to avoid is the use of slang language or technical abbreviations given without explanation. It’s important to use the official terminology. “Hoover” and “Jacuzzi”, for example, are brands, not products. They should be replaced with “vacuum cleaner” and “hot tub”.

Slang and colloquialisms also need to be avoided: you ask someone to pass you the “remote” when you want to change TV channel, but in a manual it is more correct to write “television remote control”.

In the example above, there is even an acronym – “pfd.” In technical language, abbreviated forms like symbols or acronyms are often used. These are very useful as they save space and speed up reading, but they must be used consistently.

If a technical writer decides to use an abbreviation, the meaning should be explained the first time it appears, and then it can be used throughout the document.

For example: “The Personal Flotation Device (PFD).”

But be careful! The abbreviation must be written consistently. Don’t use “PFD” in one sentence and “pfd” in another. As well as this, if the manual contains many different abbreviations, it can be useful to create a list where users can find explanations for them all. The user can then consult this list if in doubt.

5. Using a redundant style

This table shows the most common mistakes and suggestions for writing more direct and understandable sentences.

Rule	Form to avoid	Recommended form
Use active voice instead of passive voice.	The antenna cable must be connected to the plug.	Connect the antenna cable to the plug.
2.48	The software is used to control the movement of the machine.	The software controls the machine’s movements.
Prefer the indicative mood over complex constructions and verb moods like the conditional.	Should the device present manufacturing defects, consult customer service.	Contact customer service in the case of manufacturing defects.
Replace noun forms with verb forms.	Users have an opportunity to make use of the right of withdrawal.	Users may return products.
Use direct expressions.	Do not let the tool fall.	Do not drop the tool.
Choose short expressions.	it is capable of transmitting it allows to check	it transmits it checks

6. Writing units of measurement incorrectly

Units of measure are among the most common items in technical manuals, but there is a lot of confusion as to how to write them. For example, the following are incorrect:

The correct forms are:

Essentially, there needs to be a space between the number and the unit of measure, and the unit of measure should be written according to the relevant international standard.

If in doubt, you can consult the International System of Measurement Units, which lists the standards for writing units of measurement and their symbols.

7. Not adapting figures to the target market

Numbers and units of measurement should also be adapted to the target market. Technical documents translated into English from other European languages, for example, often mistakenly use a dot instead of a comma when separating thousands in numerical figures, and vice versa when marking decimal points. In English, decimal numbers are separated by a dot, and thousands by a comma:

• English: 15.10 - Italian: 15,10
• English: 10,000 - Italian: 10.000

This can lead to even more confusion if the sizes and scales referred to are not clear from the context, and the amount uses three digits:

390.142

Is that three hundred and ninety thousand... or 390 point one four two...?

Units of measurement need to be converted to the system in use on the market the manual is meant for. There are even some systems that do not use decimal subdivision, such as the Imperial measurement system used in the UK, Canada, Australia, United States and even the Philippines, to name just a few countries.

Let’s take length measurements as an example: while most of the world uses centimetres and their relative multiples or subdivisions, the Imperial system uses feet and inches. One inch (symbol: in) corresponds to 2.54 cm, while one foot (ft) corresponds to 30.5 cm. In this case the values are the same in both systems. However, if we look at measurements of volume, we see that one gallon (Imp gal) corresponds to 4.54 litres in the British system and 3.78 litres in the US system.

It is important to be aware of these differences, both so that users can understand the data reported and because failure to adapt units of measurement can lead to mistakes.

8. Not writing instructions in the logical order in which they should be carried out

In order for instructions to be well understood, and to allow users to use a product immediately, the information needs to be presented in a clear and orderly way.

There are two basic tricks to this:

• each sentence should express just one concept
• the instructions should be given in the logical and chronological order in which they should be carried out

This sentence contains several pieces of information and the sequence of actions does not reflect the order in which they are to be performed. We can make it clearer:

As well as rewriting the sentence, we have laid out the information in an orderly fashion using lists: one bulleted list, and one numbered. The bulleted list introduces a list of items, while the numbered list shows the order to perform the actions in.

9. Not improving writing with controlled languages

Controlled languages are natural languages that use a reduced number of syntactic-stylistic rules and vocabulary. They were developed to simplify and standardise technical document writing, to improve the legibility and comprehensibility of texts, and to reduce ambiguity.

The best known are:

• the ASD-STE100 specification, or Simplified Technical English, used in the aerospace industry
• Italiano Tecnico Semplificato (ITS), developed by Com\&TEC, the Italian Association for Technical Communication
• Español Técnico Simplificado (ETS) for Spanish
• Français Rationalisé for French.

How are controlled languages structured?

Both Simplified Technical English and Italiano Tecnico Semplificato are structured on two fronts:

• linguistic instructions
• vocabulary

Linguistic instructions describe the language’s grammatical, syntactic, and stylistic rules, while the vocabulary collects a restricted number of terms to use for writing a text.

What are the rules of controlled languages?

Each controlled language has its own rules, but they do share some common principles:

• a sentence should contain a limited number of words, at most 25-30
• each sentence should express just one concept
• always write the same sentence to express the same concept
• use the active voice instead of the passive voice
• do not use verbal moods that are difficult to interpret, like subjunctive or conditional moods. Use the indicative instead
• do not omit subjects, articles or demonstrative adjectives
• do not use pronouns, but repeat the noun
• do not use synonyms, but repeat the word or term
• do not use idiomatic expressions.

If these requirements are too complex or rigid, if there are not the resources to adopt controlled language in its entirety, or if outside experts cannot be used, you do not need to apply them all.

But you could take a cue from these principles and create authoring rules for your own business, using official terminology lists and with words to use or to avoid.

Controlled languages are not only developed to improve written communication in the technical sphere, but also to increase a text’s translatability. Thanks to the consistency at the very foundation of linguistic choices, and the simplification of structures, these languages help reduce translation costs and times. What’s more, they are also especially well-suited to writing texts to be processed by machine translation systems.

If you want to learn more about this subject, you can find the post “Controlled Languages” on our blog, featuring an interview with Daniela Zambrini, since 2014 associate member of STEMG, the working group responsible for maintaining the ASD-STE100 specification.

10. Not structuring information in a logical or orderly way

A manual is not a book. The average user doesn’t usually read it from the first page to the last.

How often do we buy products and try to use them without even reading the instructions? At a certain point, we realise we’re incapable and start to leaf through the manual, looking for the information we need. Or perhaps we manage to set it up, but without knowing what that last component is or where it goes, and we can’t find the reference to it anywhere in the manual.

Unless the instructions are two pages long or less, it is useful to include:

• a table of contents
• a list of abbreviations
• an index of figures and tables
• a list of key words in alphabetical order
• exploded diagrams with components and a key
• a glossary of all the technical terms with explanations.

All these elements allow the user to find what they are looking for easily.

Those who work in the field of manuals and technical writing use (or should use) special software for the creation and management of technical documents and manuals. These are tools which help you go beyond the limits of Word and InDesign, and which make content management and updates notably easier.

They are grouped under the acronym CCMS, which stands for Component Content Management System and refers to their main function: the ability to structure content in a granular fashion, by components, rather than at the document level.

For example, if user and maintenance manuals for different machines or products share the same safety warnings or cleaning notes, CCMS software allows you to create that common content once and then reuse it as many times as needed.

These systems typically use standard formats for creating structured information. The two best known standards are:

• DITA (Darwin Information Typing Architecture) and
• DocBook

but there are also other sector-specific ones, such as SCORM for creating training content or S1000D for the defense and aerospace industries.

11. Using poor quality or unclear illustrations

Content is not the only thing that counts in a manual. Graphics and visual information are important too. Remember that a manual likely won’t be read at a desk, but rather at inconvenient work stations with poor lighting or in narrow spaces.

Titles, bold lettering, well-spaced paragraphs, and notes in the page margins all make reading easier, as do visual elements that support the text. Images, drawings, exploded diagrams and pictograms all draw attention, make the text easier to understand, allow you to write less and, ultimately, to save on translation costs too.

Look at this image taken from an instruction manual for a child’s car seat:

Source: https://www.chicco.it/content/dam/chicco/it/pdf/in-viaggio/seggiolini-auto/8058664079445/youniverse-manuale-istruzioni.pdf

The image’s message is clear: you just need to glance at it to understand that the distance between the lower part of the headrest and the child’s shoulder should be two centimetres.

Figures and tables should be numbered and captioned. They will also need to be updated constantly: if text revision also affects images, these need to be changed as a result.

In multilingual manuals, if the images also contain text, this should also be translated. To learn more about this topic, read our post “How to Translate Text Contained in Images”.

How can I check if a manual is clearly understandable?

Manual writers are often field experts and may overlook elements that seem simple to them, but that are by no means straightforward for the end user. One way of checking whether the content is clear is to have it read and, most importantly, put into practice by someone who is unfamiliar with the product.

However, even if you do this, it’s not always possible to prevent every single issue. Once a product is on the market, customers will be able to report problems and send in complaints. This feedback is very useful and should be made the most of to improve your manual.

12. Not planning the manual’s translation from the first draft

European Commission directive 2006/42/CE stipulates that “every machine must be accompanied by instructions for use in the official language or languages of the member State in which the machine is available on the market and/or used.”

Making the technical documentation available in the languages of the markets you are selling on is not only a legal obligation, but it will also allow you to reach your clients more effectively and, as we said at the beginning of this post, to reduce after sales-related costs.

Many businesses make the mistake of saving on translation-related costs: it is often assumed that it is enough to have a manual in English, or to have it translated by internal staff who, though they may be experts in the field, do not have the necessary translation skills.

When you need to translate a manual:

• read our guide to choosing the right language service provider for you
• write original content considering that it will need to be translated
• make a person available to the translation provider to resolve any doubts

6 concepts to conclude

1. Simplicity, clarity and coherence are key when writing a manual.
2. Users want to be able to use the product in as little time as possible: include pictures and drawings to facilitate understanding and elements such as table of contents, index of abbreviations, and list of keywords for easy reference.
3. Remember that users don’t have the same training as the manual writer: don’t take anything for granted.
4. Put yourself in the users’ shoes and try to anticipate their questions.
5. Be as careful with the translations as with the original.
6. A well-written manual will let you save on the costs of support and complaints.

Recommended reading

• IEC 82079-1:2019 standard, “Preparation of instructions for use -- Structuring, content and presentation General principles and detailed requirements”, available on purchase on ISO.org.
• ASD-STE100 Specification (Simplified Technical English).
• Italiano Tecnico Semplificato by Ilaria Gobbi. [REMOVE] [REMOVE]