Ten Tips for a Better Manual

1.

Know your audience.

This is Rule Number One of technical writing.

If the manual is for novices, make sure that the average person can understand what has been written (that is, don't include a lot of jargon or technical assumptions). This is sometimes very difficult for a writer who is a subject matter expert. He or she may have forgotten what it's like to know absolutely nothing about that particular subject. Likewise, if the manual is for experts, be sure not to "dumb it down." Don't include graphics or explanations that are not needed.

2.

Keep it simple.

Just stick to the facts. In an instructional manual, there's no need to include the whole history of why a certain procedure was implemented. Just tell the reader how to do what needs to be done. Likewise, there is usually no need to discuss theories or philosophies. If you feel that's necessary, include that type of information in an appendix.

Telling the reader more than he or she needs to know is a trap that many writers fall into, especially those who have been deeply involved in developing the process or product.

3.

Make it available online.

There are many benefits to putting information online:

• Users can get to what they want more quickly using the search functionality.
• It's much easier (and less expensive) to update online documents than their hard copy counterparts.
• Hyperlinks make navigating through large documents easier.

In some environments, access to online manuals may not be appropriate (for example, if the user's work area doesn't include a computer). However, even in those environments, it's a good idea to have manuals available online as well as in hard copy format. Someone may have forgotten his or her hard copy manual, and having that document online means it's easy to print the whole thing or even one page.

4.

Be consistent.

Lack of consistency is one of the biggest factors causing reader confusion. If a part is called a Widget in Chapter 1, and then the same part is called an Enhanced Widget in Chapter 2, it's very easy for the reader to think that a completely different part is being referenced.

5.

Have somebody else read it to see if it makes sense.

Many people who have written a manual feel that their words shouldn't be tampered with. However, it's often amazing to see what happens when someone unfamiliar with the subject matter tries to interpret those words. In many cases, information totally clear to the author makes little sense to the reader. The bottom line is that EVERYONE needs an editor.

6.

Proof everything (at least once).

In this case, we're not talking about content—we're talking about all those nasty little typos, incorrectly numbered steps, grammatical errors, etc. Your word processor's spelling checker will eliminate most spelling errors. But there are a raft of other little nitty-gritty errors that can make even the most well-written manual look like a sloppy piece of work. And a computer isn't smart enough to find these subtle errors! Rereading, by you and by someone else, is essential.

7.

Include an index.

An alphabetical index of terms is a vital way for users to find information in a document. An index is helpful in ways that a table of contents can't be, for example, when a topic is mentioned repeatedly throughout a manual in different contexts.

8.

Use graphics wisely.

Resist the urge to stuff your document full of unnecessary graphics. Save the graphics to illustrate points that may be difficult to describe in words. And always include annotations (arrows, call-out boxes) to direct the reader to the significant items.

Another reason to reduce the number of graphics is that in online documents, they can slow down the time it takes to load a web page, download a file, or even scroll.

9.

Get it done on time.

This tip may seem obvious. So why, then, are so many manuals delivered "later?" The reasons for this range from a). oops—we forgot we needed one to z). we couldn't start the manual until we finished the product.

If you're rolling out a new product or process, it doesn't help to get the manual to the user three weeks late. Delivering the manual along with the product reduces the learning curve and decreases error rates. Furthermore, users expect to have the manual delivered with the product—so if it's not there on time, frustration sets in immediately.

10.

Create a schedule.

Creating a schedule is what allows you to get the manual done on time. Build the schedule long before work begins on the manual, and be sure to allow enough time for multiple reviews and revisions.