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.
About the author
Dr. Philip Hodgson (@bpusability on Twitter) holds a B.Sc., M.A., and Ph.D. in Experimental Psychology. He has over twenty years of experience as a researcher, consultant, and trainer in usability, user experience, human factors and experimental psychology. His work has influenced product and system design in the consumer, telecoms, manufacturing, packaging, public safety, web and medical domains for the North American, European, and Asian markets.
Love it? Hate it? Join the discussioncomments powered by Disqus
Online training in user experience
Get a job in UX and improve your web site's UI design with these in-depth, hands-on user experience training courses. More details
Every month, we share an in-depth article on user experience with over 10,000 newsletter readers. Want in? Sign up now and download a free guide to usability test moderation.
User Experience Articles
Our most popular articles
Our most commented articles
Our most recent articles
Search for articles by keyword
- 7 articles tagged accessibility
- 4 articles tagged axure
- 5 articles tagged benefits
- 12 articles tagged careers
- 8 articles tagged case study
- 1 article tagged css
- 8 articles tagged discount usability
- 2 articles tagged ecommerce
- 8 articles tagged ethnography
- 14 articles tagged expert review
- 1 article tagged fitts law
- 3 articles tagged focus groups
- 1 article tagged forms
- 6 articles tagged guidelines
- 10 articles tagged heuristic evaluation
- 7 articles tagged ia
- 14 articles tagged iso 9241
- 8 articles tagged iterative design
- 3 articles tagged layout
- 1 article tagged legal
- 10 articles tagged metrics
- 3 articles tagged mobile
- 6 articles tagged moderating
- 3 articles tagged morae
- 2 articles tagged navigation
- 9 articles tagged personas
- 15 articles tagged prototyping
- 7 articles tagged questionnaires
- 1 article tagged quotations
- 4 articles tagged roi
- 15 articles tagged selling usability
- 12 articles tagged standards
- 39 articles tagged strategy
- 2 articles tagged style guide
- 4 articles tagged survey design
- 5 articles tagged task scenarios
- 2 articles tagged templates
- 21 articles tagged tools
- 46 articles tagged usability testing
- 3 articles tagged user manual