Writing user manuals

Contents

• Know who you are writing for
• A good start is your Table of Contents
• Collect all necessary information
• Actually writing (illustrating?) your user manual
• Choosing the appropriate format

Know who you are writing for

If you know who your target group is, you know two very important things that are necessary to write a high-quality user manual.

First, you know something about the tone of voice. If you are writing a user manual for first-time users of an alarm system, it could be that you need to explain how to set up the sensors in a room. You should motivate them to have a look at several examples so that users can use the sensors effectively. This requires setting up some kind of motivational relationship with the reader so that he/she gets the most out of your product.

However, if your product does not need an introduction because users will be familiar with it right from the start, you could leave out examples or any advice to experiment. Your language could be more business-like, just pointing out where the relevant buttons are.

The second consideration aligns pretty well with the first point made. Any target group values its own level of detail. It is not necessary to explain to maintenance personnel how to clean a manufacturing machine. People from this group would be offended if you would spell out what to do. However, it is necessary to tell personnel from a small company how to replace printer cartridges. Or to inform them when a printer would need internal cleaning.

It is always important to keep in mind who you are writing for.

A good start is your Table of Contents

Why is a Table of Contents a good start? Because a Table of Contents forces the writer of a user manual to think about what he/she wants to say in what order. Of course, there will be a foreword or an introduction in any user manual. Without doubt, there will be safety instructions at the beginning of the manual as well. There will also be some maintenance issues at the end. But what should you put in between those chapters?

This all depends on the product itself. For some products the settings are important: one day a pump may work ‘normally’, another day it may be best to set it in reverse. This could depend on water levels, for example. A chapter called “Everyday settings” could be appropriate here. Another chapter may be about collecting information how much water has been transported and to where exactly. One could call such a chapter “Monitoring results”.

Take another example: a so-called ‘multifunctional device’. For a ‘multifunctional’ the chapters in a Table of Contents could be based on, indeed, its different functions: printing, copying, scanning, faxing, and so on.

As long as there is some logical order that the user can relate to, the user manual lends itself for effective scanning. In this respect, it is absolutely essential that each chapter and each paragraph has a clear-cut title: “Printing using your computer”, “Copying without your computer”, “Scanning to your computer” and so on.

Collect all necessary information

A technical writer has the reputation of being inward looking, interested as he/she is in only one thing: technology.

This reputation does not do him or her justice. A technical writer should know a lot about voltage, current, resistance and megahertz. But he should also know how to collect all the necessary information. Quite a lot information may be available on paper or digitally. One could think of a risk analysis, 3D CAD illustrations, data sheets and so on.

But it is quite possible, even probable, that this information does not answer all the questions a technical writer has in mind. After all, a technical writer wants to place himself in the shoes of the user. If the documentation does not elaborate on the need for a pump to be set in reverse, he needs to ask the experts: why is it necessary to set this specific pump in reverse?

This means a technical writer has to have communication skills. He also has to have social skills. Placing yourself in the shoes of another person has everything to do with wanting to know the other person.

Portraying a technical writer as a ‘technician only’ would be a mistake. It takes more to write a user manual than being ‘tech savvy’.

Actually writing (illustrating?) your user manual

OK, you have collected all necessary information. Now it is time to actually write your user manual. Three considerations spring to mind.

The first consideration has to do with minimalism. Minimalism is a philosophy not to spend more words on a subject or task than is strictly necessary. It is not necessary to tell the reader that a valve is available in three colors when the only valve on a tank is red. A user only needs to know how to use the valve and when. This may sound very obvious, but proves to be quite a challenge in (too) many cases. Some companies do not throw away their ‘marketing head’ easily.

The second consideration is: always use Simplified Technical English if you want to be business-like. Simplified Technical English, or STE for short, does away with words that are ambiguous, such as ‘to carry out’. ‘To carry out’ could mean ‘taking something away from a certain location’, but also ‘taking action’. In STE, only the verb ‘to do’ will do. Also, STE limits the number of words in a sentence to roughly 20. This make any sentence easy to understand.

The third consideration is also very important. Why use text if an illustration works just as well or even better? After all, an illustration takes away the need to translate text. But even more important is the fact that people are first and foremost visually oriented. The saying ‘A picture tells you more than a 1,000 words’ implies that people grasp the meaning of something faster and better when it is illustrated. You cannot present all information visually (“Be sure the holes are free of wood chips and saw dust”). But where you can, the benefits for the user can be enormous. Thus, ‘writing a user manual’ takes on a whole new meaning.

Choosing the appropriate format

There still is one choice left: what kind of layout do you want? Or, in jargon: what is the template you want to define so that your user manual not only matches the wishes of the user, but also your corportate identity? Consistency is key here: every chapter and every paragraph should look the same.

There are software tools available that help you to define a professional template. What’s more: there are content management systems on the market that can transform a single source text into any format required, whether this format would be an A5 booklet, an A4 book, a PDF file (portrait or landscape) or a website that adjusts itself automatically when presented on a computer or tablet or smartphone.

Companies that are specialized in writing user manuals know how to help you choosing the relevant formats – in case you would need advice.