7 Cures for Unusable User’s Guides

A few years ago, we wrote the 7 Cures Series to help people with various problems they asked us about. The information is still useful.

This article offers tips to improve the writing in your user guide so it actually helps people.

1. Get organized.
   Look at the organization of the user’s guide. Most user’s guides are difficult to use because no one took the time to organize the document. Use an outline.

2. Standardize on terms.
   Be consistent in your terminology. Create a style sheet if necessary. If you are unsure of common terms for software look at other user’s guides from large companies such as Microsoft. If you’ve decided that user’s must click buttons, and select items from menus, never say press buttons or choose items from menus.

3. Write in the present tense.
   The reader is following your instructions now, not some nebulous time in the future. Using future tense makes you wonder when something is going to happen. This type of confusion is probably not something you want in your manual.

4. Write accurately, clearly, and consisely.
   The nerd world is filled with endless acronyms and confusing terms. Eliminate as much jargon from your user’s guide as possible. People don’t read user’s guides for fun, so use short, easy-to-understand words.

5. Write in the active voice (not the passive voice).
   If your sentence needs a subject, try the word you. Tell users what you want them to do. Use direct wording. For example:

   You must turn on the computer.

   or

   Turn on the computer.

   is more compelling than

   Before beginning, the user is required to activate the CPU.

6. Create an accessible layout. Make it readable.
   People won’t read a user’s guide they can’t stand to look at. Make the hierarchy of topics obvious. If someone has bothered to pick up the manual, they are probably unhappy; don’t make it worse. Take a lot of time with the index. Studies have shown that a good index reduces technical support calls and training time. Think about how annoying it is to use a manual with a bad index.

7. Verify information and/or test all procedures.
   Okay, this advice may seem obvious, but when you consider the type of deadlines that most writers must meet, it’s no surprise that many user’s guides do not agree with the software. Take the time to make it right.