Tips for writing user manuals

User manuals have a bad reputation. In a recent USA Today poll that asked readers "Which technological things have the ability to confuse you?" user manuals came out top! Increasingly companies are rethinking the way they approach user manuals. Here are some suggestions for improving the usability of user manuals based on our experience writing them.

— Philip Hodgson, June 4, 2007

These guidelines are based on:

Best practice principles.
Principles of good information design.
Aspects of human perception, cognition and psychology as it pertains to reading.
Our own experience of user testing various kinds of user manuals and documentation and seeing what works and what doesn't.

We have arranged the tips into the following sections:

General guidelines
How to create a great first impression
How to enhance findability
How to give instructions
How to design individual pages
How to design the physical manual

General guidelines for user manuals

Provide a real (physical) user manual with the product: don't make people read a pdf.
Make sure the instructions actually map on to the product in all respects.
Include a one-page quick start guide.
Present instructions as step-by-step procedures.
Tell the user what functions there are, and what they are for — not just how to use them...
...but avoid marketing waffle (they already bought the product!)
Ensure that the writers are part of the product design team.
Write the user manual in synch with the product's development timeline — not under pressure of shipping deadlines.
Make sure the writers have the product, understand the product, and actually use the product as they write.
Consider the needs of disabled users (i.e., low vision, colour-blind) and provide alternative manuals in Braille, large print, audio etc.
User-test the product and the user manual with real users (including disabled users).

How to create a great first impression

Many users never actually get as far as the user manual. It is often tossed aside as being either secondary, or just too difficult to deal with. When this happens, the user, the product and the writing team all suffer in some way. In order to get past this point the user manual must make a strong and positive first impression. These guidelines can help.

Avoid a text-book look (landscape formatting can be less threatening).
Use paper that is commensurate with the quality of the product.
Make purposeful and effective use of colour.
The user manual should not be too big or too heavy...
...or too small or too flimsy.
Make effective use of pictures and diagram.
Provide lots of white space.
Use a clean, readable san-serif font.
Include a help-line number.
Use a single language.

How to enhance findability

Users quickly get frustrated when they cannot find what they are looking for in the user manual. Often this is due to the fact that the key words the writer has used are not the key words that users may search for. Here are some guidelines that will help users find what they are looking for.

Organize information hierarchically.
Code the hierarchy with tabs, colours etc.
Divide into sections ordered by:

Chronology of use.
Frequency of use.
Functional categories.
Expertise level (beginner vs. expert user).

Denote importance by using contrast, colour, shading, emboldening etc.
Work with real users to identify likely key words (these can be learned during usability testing).
Provide a key word index using the terminology of the user.
Ensure that the index includes likely synonyms.
Provide a glossary of technical terms.
Include a (genuinely useful) trouble-shooting section.
Use colour-coding to aid navigation.
Make the quick start guide readily accessible.
Avoid unnecessarily cross-referencing to other parts of the user manual.
Avoid duplicate page numbering in multi-language guides (better still, avoid multi-language).
Clearly display the help-line number.

How to give instructions

Clearly this is the primary role of the user manual. It is critical that the instructions are easy to read and are understandable by all users. Many user manuals have instructions that are incomplete, incorrect, or simply have no bearing on the actual product. Here are some guidelines to help make instructions easy on the user.

Provide step-by-step sequences in the correct order.
Follow the timing and sequencing of the actual operations .
Provide visual stepping stones (e.g. Step 1, Step 2 etc.)
Avoid lengthy paragraphs.
Use everyday words and terms: avoid jargon.
Explain what a function or feature is for (in basic practical terms) as well as "How to" instructions.
Check that the instructions match the actual product.
Explain symbols, icons and codes early.
Avoid creating dead-ends.
Avoid patronising the user.
Do not assume the user has prior experience or product knowledge.
Usability test the instructions alonside the product using naive users (not designers or product experts).
Write in the present tense and the active voice.
Write the steps to task completion while doing the actual task on a real product. Have an independent user then follow the steps (literally) with the product and check that:

It is easy to work through the task from start to finish.
It is easy to break out of task and get back in.
It is easy to jump into the user manual half way through a task.

How to design individual pages in the user manual

In addition to effective instructing, the use of colour, the text and fonts used, and the icons and graphics can all either make for an easy experience or can derail the user. Here are some suggestions.

Ensure that font size is adequate (use at least 12 point font).
Ensure high text-to-background contrast (black on white is best).
Use san-serif fonts.
Avoid using multiple font styles.
Font weight can be used sparingly to denote importance.
Use colour coding consistently.
Provide plenty of white space between sections and around images and paragraphs.
Provide a section (or margins) for the users to make their own notes.
Use consistent layout from page to page.
Test your use of colours to ensure they can be read by colour-blind users.
Avoid using saturated blue for text and small detail, and never use blue on a red background.

How to design the physical manual

User manuals are used in many different kinds of environments: they may be used indoors or outdoors, they may be used with good light or with dim light, they may be used in a comfortable and user friendly setting or in an environment that is hostile or even dangerous. Here are some basic guidelines to ensure your user manual will survive actual use.

Ensure that the user manual can lie flat on a work surface when opened.
Consider the environment of use and if necessary provide a robust user manual.
Consider whether the user needs to hold the user manual and work at the same time.
Provide durable covers and pages.
Consider whether the user manual needs to resist water, oil, dirt, grease etc.

Want this article on your web site?

You can republish this article on your own web site or intranet. You don't need to ask permission so long as you include this citation at the end of the article.

Free Usability Newsletter

Let us notify you when we publish more articles like this. Benefits of signing up.

If you liked this, try…

Usability Expert Reviews: Beyond Heuristic Evaluation

Most people that carry out usability expert reviews use Jakob Nielsen's ten usability 'heuristics'. Many of these guidelines are common sense but they are not based on substantive research. The International usability standard, BS EN-ISO 9241-110 proposes an alternative set of seven guidelines. These guidelines have the benefit of international consensus and they can be applied to any interactive system.

Red route usability

Important roads in London are known as 'red routes' and Transport for London do everything in their power to make sure passenger journeys on these routes are completed as smoothly and quickly as possible. Define the red routes for your web site and you'll be able to identify and eliminate any usability obstacles on the key user journeys.

Tips for writing user manuals