Slipping Between the Covers of a Technical Document
When you prepare a lengthy user manual, include all the information readers need and make the information easy to find. Following are guidelines for what to include.
Table of contents
Whenever the manual is more than 15 pages, include a table of contents to help readers easily find what they need. Use leaders (. . . . . . .) to connect the subjects to the page numbers so readers can run their eyes across the page.
Some writers use internal chapter numbers. For example, Chapter 1 is numbered 1-1, 1-2, 1-3, 1-4; Chapter 2 is numbered 2-1, 2-2, 2-3, 2-4, and so forth. This is different from consecutive numbering (1, 2, 3, 4). Use internal chapter numbers when you anticipate updating one or more chapters. Doing so keeps you from renumbering (and reprinting) the entire manual.
If there's a hint that your readers may not understand all the terminology in the manual, include a glossary at the end. Defining a word the first time you use it isn't always adequate because readers won't read your manual from cover to cover as if it's the great American novel. They'll use it for reference when they have a question.
If you write online help, use pop-up windows for terms. If you write Web documents, create a link to the glossary.
Not all manuals need an index. The content of the manual is the gating factor, not the length. Put yourself in the mindset of the reader and ask: If I were reading this document, would an index be helpful? If you think an index would help you, include one. Be very sensitive to the logical search words that the reader may look for.
Here's a story of a woman who bought a new car. She drove about 25 miles when she ran over some glass and got a flat tire. The woman wanted to change the tire herself and pulled out the owner's manual. She checked under the following letters in the index:
- f for flat
- t for tire
- j for jack
- c for change
The woman couldn't find the information and couldn't believe that the manual neglected such an important entry. She finally gave up and phoned the American Automobile Association (AAA). When she returned home, she began checking every index entry. Yes, there was an entry for changing a flat tire. It was under h for "How to change . . ."
When writing for the Web, include a site map or something equivalent.
No matter how well you write a technical manual, readers will have issues. The way to address these issues is to include a section on troubleshooting. Table 1 is a great troubleshooting section from the Kodak DC215 Zoom Digital Camera User Guide. It breaks out the problem, cause, and solution.
Table 1: Troubleshooting a Kodak DC215 Zoom Digital Camera
Picture is too light.
Flash is not needed.
Change to Auto flash. See page 13.
The subject was too close when the flash was used.
Move so there is at least 1.6 ft (0.5m) between the camera and the subject.
The light sensor is covered.
Hold the camera so your hands or other objects do not cover the light sensor.
The Exposure Compensation is set incorrectly.
Decrease the Exposure Compensation. See page 14.
Stored pictures are damaged.
The camera memory card was removed when the Ready light was blinking.
Make sure the Ready light is not blinking before removing the card.
Pictures remaining number does not decrease after taking a picture.
Image Resolution and Quality settings do not take up sufficient space to decrease the picture remaining number.
The camera is operating normally. Continue taking pictures.
Picture is not clear.
The lens is dirty.
Clean the lens. See page 65.
Subject was too close when picture was taken.
Stand at least 1.6 ft (0.5m) in wide angle, 3.3 ft (1m) in telephoto.
Subject or the camera moved while the picture was taken.
Hold camera steady until the picture is taken.
The subject is too far away for the flash to be effective.
Move so the subject is less than 10 ft (.3m) away.
When you include a section on troubleshooting — or frequently asked questions (FAQs) in an electronic document — you spare the folks at the Help desk cauliflower ear. Here's how to think through what to include in the troubleshooting section:
- If this is the first edition of the manual, think of the questions or problems your readers may have. Be sure to include questions that testers had during alpha and beta testing.
- If this is a second or third edition, ask the people at the help desk for the most commonly asked questions.
To improve the quality of your manual for the next printing and to improve the quality of your own writing, include a feedback form. This form gives readers a chance to let you know what they liked and didn't like about the manual and to let you know of any errors they found.
Don't be disturbed if you get mainly negative feedback. Readers who are pleased with the manual generally don't bother to respond. Readers who aren't pleased want to let you know. Take this feedback as constructive and use it as an opportunity to improve your writing technique. Don't take it personally.