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 diagrams.
• 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 alongside 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.

Interested in this topic?

Find out more on our 3-day, user experience immersion seminar.