Glossaries and Appendices
As we've said, we need to make sure that the terms we're using are understandable, but we don't want to bog our copy down with so much information that the user can't get started. One way to get the best of both worlds is to make your instructions fairly lean while providing more information for those who need it by including optional reference sections in your user help manuals.
Glossaries.
Glossaries are like brief dictionaries, defining a set of terms used within a text for those who don't understand them. Including bold text or some other way of highlighting terms available in the glossary can be useful for the reader.
- Terms highlighted in bold are explained in the glossary (see page XX).
- The ignition system is ignited by turning a key in the appropriate slot. The key is a security measure designed to insure that only authorized individuals operate the vehicle.
-
The ignition key slot is located on the right side of the steering column below the steering wheel.
When the reader turns to page XX, you will find a glossary explaining terms in greater detail, possibly with an illustration as well. -
Steering Wheel. A circular object located on the driver's side (left side) of the vehicle. The driver can control the vehicle's direction by turning the steering wheel in the direction they wish to travel. (Include a photo or drawing.)
Appendices. For topics that take more than a glossary entry to explain, you may wish to include an appendix. Appendices are supplementary chapters toward the end of the manual that provide more detailed information for those who need it. Appendices can help keep your instructions concise enough for advanced users while including enough detail to help beginners get up to speed. -
Insert key in ignition slot and turn (For more information on ignition systems and how they work, see Appendix 1.)
If your product lends itself to online help files, you can link directly to glossaries and appendices by means of a hyperlink, either by prompting readers to "click here for more information" after a term is introduced, or by linking directly to the word. - Insert key in ignition slot and turn.
- Insert key in ignition slot.
Sell the Benefits
Reading a manual and learning something new can be challenging and stressful for your users. While you're teaching them to use the product, you might want to remind them that all this work reading the manual is worth their time and effort. Spend a little time selling the benefits of knowing how to use the product and reminding them what they have to gain.- If you've successfully started the car, congratulations! You're almost ready to travel. Soon you'll be able to take yourself and all your extraterrestrial buddies anywhere you want to go. But first, we've got just a little more to learn. Next up, shifting into gear!
Get Feedback
We've said it before, but it bears repeating. A great way to see if you've got the right amount of detail is to try to put yourself in your reader's shoes (assuming aliens wear shoes). When you've done the best you can by evaluating your own work, try it out on some trial users. Try getting feedback from less technically oriented employees at your company, or assemble a team of beta testers to try using your manual and operate your product. You will want to know that you've done everything you can to provide help that is truly helpful.
]]>