How To Write an Effective Manual

Erin Massey of the Chicago Tribune newspaper (registration required) has written a nice article on the importance of product manuals. Although she interviewed me and included several quotations, she missed the most important lessons of all. So let me provide them here.

Is a manual important? Yes, but even more important is a well-designed product, one so well conceived and constructed that either the manual is not needed at all, or if it is, where the manual can be short, simple, and easy to understand and then to remember. How is this accomplished? By following some simple rules.

1. Hire excellent technical writers. The technical writing profession is an essential component of any design, just as important as designers, interaction and usability specialists, and engineers.  
2. The manual writers should be a part of the design team. Ideally, the manual is written first, aimed at being short, simple, and understandable. The designers and engineers help oversee the writing, for when the manual is complete, it will serve as the product specifications that they will follow. Therefore, they must buy into the design from the beginning. The ideal manual need only be consulted once for any point or activity: Someone should be able to read each section of the manual, say “Oh yes, I get it,” and never need it again.
3. The manual should be activity-centered. Pick the most basic activities and explain how to accomplish them. Make the explanations short and simple, with illustrations. Today, all too often, manuals follow the “let's explain every knob and button and menu item in turn.” Yuck! That provides no understanding of how to accomplish anything. Remember: people do not want to read manuals — they want to do their activity. Help them get right to work, with minimum reading.
4. Test the manual with people chosen to match the intended user community. How do you test a manual before the product is even designed? The manual testing should be done in conjunction with the first design tests using the rapid-prototyping techniques used by the your Human-Centered Design team. They don't do rapid, frequent prototypes? You have a bad team — change it.
5. Put legal warnings in a separate booklet or in the Appendix. When a manual is needed, it is needed right away, and having to work one's way through pages of legal warnings only increases the anxiety level and decreases the pleasure of the product. Morevoer, people skip these anyway, so they are ineffective. .

Comments contributed by readers

“Here's another tip for providing (if not writing) an effective manual: include storage for the manual on the product, if at all possible. Can you find the manual for your stove, your refrigerator, your toaster oven, your microwave, your vacuum cleaner, your TV, your Tivo, your thermostat, your furnace, etc.? I have to keep the manuals for all of those filed separately from the items, which leads to two problems: they're usually not where they're needed, and they might not get put away promptly after they are used. By contrast, my car (a 2004 Audi A6) has a dedicated slot for the owner's manual right under the steering wheel, and every car has at least a glove compartment to put the manual in.”

My response: An excellent point for larger items, obviously not practical for small ones such as cellphones. Of course, it would be better to design the product so that no manual is rquired. Alternatively, consider a small “Cheat Sheet” manual of useful reminders for the most difficult items that is small enough to keep on the product itself. (Note: most of the reduced instruction sets I have seen explain the common operations and not the obscure ones: the common items should not require reminding — it is the infrequent, obscure ones that need the reminders.)

“We were trying to figure out how to use our rice cooker this weekend and the instruction manual is ridiculous. It is very long — but indicated that we could not possibly use the product without reading the entire manual — and it started with a extraordinarily long list of “not-to-dos” and finally listed some “to-dos.” It at one point referred us to another section of the book for amplification on a topic, and when we went there there was not reference to the topic. I hope more people hire you to work on manuals.”

My response: Marketing people seem to think that big manuals are good. Wrong: the bigger the manual, the more confused the reader.

Norman's Law: The number of readers is inversely proportional to the square of the length of the document.

Afterward

This article has been blogged on the Tech-Whrl-list, a forum for Technical Writers. Some agreed with me, some disagreed. Some misunderstood, some did understand. In other words, a typical blogfest. Still, if you are interested in the practical difficulties of carrying out these ideas, you might enjoy the blogging commentary. I do point out that my article was of necessity short and simplified. many of the practical considerations mentioned by the writers are absolutely correct, and my wish to get rid of the legal jargon that prevents the reader from getting to the manual may prove to be a legal impossibility. So read the blogs with the same delight and confusion as I did. That is real life: delightful, confusing, frustrating.