- Formerly known as "Writers Manual" -

The Writer Gazette welcomes you!
Look to us for all your writing resource needs!

Creating Successful User Manuals
by Linda Adams

When someone buys a software program, the first thing he usually complains about is the user manual. It's hard to find what he's looking for and the instructions are confusing or incomplete. Then, as he's following the steps, something happens, and he wonders, "Is it supposed to do that?!" But the instructions don't provide any answers.

So how do you write an effective user manual? Where do you start?

Know Your Audience

This is key to writing an effective user's manual. Everyone has different skill levels, and many people have only a basic knowledge. How basic? Imagine someone asking: "How do I enter text on the screen?" That's the skill level to target.

Build Confidence

Many users are convinced that if they even touch the computer, something terrible will happen. By knowing your audience, you can use your writing to help build confidence and reassure the users that they're not doing anything wrong.

Be Excruciatingly Detailed

List every step it takes to accomplish a single task. A common issue is to omit a step because it seems intuitive. Obvious, perhaps, to you, but not to every user. You don't want him staring at a message box and wondering if he should click YES or NO.

Be Specific

Refer to dialog boxes, message boxes, and buttons the way the program displays it to the user. For example, don't use vague terms in the instructions: "A dialog box opens." Well, what kind of dialog box? Tell him: "The Save As dialog box opens." This reassures him he's not making mistakes.

Be Concise

Give each step its own paragraph, and keep hat paragraph under three lines. Utilize white space. Users are busy people; they're reading the instructions to do a specific task--not to learn how to use the program. If they see a large block of text, they may not read any further. That's why those 500-page instruction books often end up gathering dust. Too much work to figure out a simple task!

Be Consistent

Use consistent terms when describing a task. For instance, if you write "Click the SAVE button, don't write "Select the SAVE button" later on. This can create confusion, especially if the user is not confident of his abilities.

Complete Instructions

Treat each task as a separate entity. One of the most frustrating things for a user is to find the subject they're looking for only to discover it assumes prior knowledge of something else. For each task, give a brief explanation of what it will do, and then start the instructions at the beginning and continue until completed.

Advanced Users

All these techniques have been focused on the beginner. What about the advanced users? Would being too basic alienate them? No. Because they'll refer to the manual for the same reason as beginners--they need to know how to do something. A sidebar can display additional techniques that are handy to know but not necessary. Call it "Time Saving Tips" or another title that will appeal to all users. This offers your users a chance to discover something new and give them a sense of pride.

What Questions is the User Going to Ask?

This is the most challenging part of writing a user's manual because, no matter what you come up with, you won't think of everything. But you may be able to anticipate issues that arise. Some questions may seem so obvious that you don't understand how the user could have missed it. If your company is replacing a program with a new one, the users may want to know why they have to change. Or why they can't do something. Add to your manual as you learn more from the users.

Ask For Help

Once you have finished the manual, ask someone try it out. Not only will they flag confusing instructions, they may also come up with more questions the user will ask and catch any embarrassing typos. After distributing a manual, one company discovered they'd spelled the product name wrong in the title! So it pays to have a fresh eye look at the manual.

The main obstacle in writing a user's manual is that it is repetitive and tedious--for you as the writer. But the user is not going to read the manual like he would read a novel. He'll use it as a quick reference. Help him feel confident when he uses the manual, and you'll have a happy user.

Copyright © 2001 Linda Adams

Linda Adams is an internationally published writer with over 30 writing credits, including The Toastmaster (June 2001), Vampire Dan's Story Emporium, and Gauntlet. You can contact Linda Adams at adams.linda.m@att.net. For more information on Linda, see http://www.hackman-adams.com

How to Write Usable User Documentation
 This popular handbook presents a step-by-step method for clearly explaining a product, system, or procedure. The easy-to-follow text--packed with examples and illustrations--explains the unique demands of this form of writing and shows how to set up the best user model. The book covers developing a modular outline and storyboard, generating the draft, revising, developing a formal usability test, and supporting and updating user documentation. Also included are a glossary of terms, a listing of books and periodicals for additional information, and an index.