Writing Software Documentation
Bynum/Peterson
Chapter 4 – Writing to Support – Reference

Where Chapter 3 addressed writing process documentation (Writing to Guide), Chapter 4 focuses on writing reference documentation. It’s Barker’s assertion that reference manuals are geared toward users who are adept at using the software and only need to go to the reference material for answers in complicated situations. He says that reference documents usually contain very little “how to” to information. Their function is to direct the user over a hurdle and allow him/her to continue on with a task.

Reference (or support) documentation can take many different forms, including:
§ Command descriptions
§ Menu overviews
§ Lists of definitions
§ Function descriptions
§ Examples
§ Error messages

Barker promotes the use of the following five guidelines to develop effective reference materials:
1. Choose the Right Form of Reference
Barker states that advanced users who go to reference materials are usually looking for a quick answer to a specific question or problem. There are several standard formats that lend themselves to different scenarios—appendices, readme files, job aids, and flipcards. These conventions allow an experienced software user to know where to expect to find the information they need.
2. Decide What to Include
When writing reference documentation a person must decide which topics to include, such as commands, interface elements, and/or definitions of terms.
3. Establish a Pattern
“Recognition through regularity” describes this guideline. A successful reference document repeats consistent patterns that provide familiarity to users.
4. Organize Reference Section
Support documentation requires making decisions on the order of material will be presented. There are two basic organizational options: alphabetical and menu-by-menu. Barker says that there is an advantage to using the menu-by-menu format.
5. Show How to Use the Reference Section
If users are familiar with the different format support documentation can take, instructions are usually not needed. However, if multiple formats are combined, an introductory section could be beneficial.