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:
- 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. - 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. - Establish a Pattern
“Recognition through regularity” describes this guideline. A successful reference document repeats consistent patterns that provide familiarity to users. - 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. - 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.
posted by Anne Peterson | 8:00 PM
9 Comments:
One of my duties at work is to serve as a webmaster for my departmental intranet site. I maintain a massive amount of technical reference data on that site. Many of the reference documents get updated regularly - some of them daily. The reference documentation is the most used portion of the web site.
The author appears to be correct when he writes that reference documentation most often is associated with advanced users. In my experience the more advanced the user - the more he/she seeks technical reference documentation.
Again, I think it's particularly important in any of the methods of writing software documentation to pay attention to the audience. I like the point that reference manuals usually contain very little how to information, but instead focus on getting the user over certain hurdles. I think if the user of the reference manual either thinks that you are talking above them or below them they will not pay much attention to what you have to say because they do not think it applies to them. They like a quick reference where they can just kind of glance at what they are stuck on and then carry on with what they were doing. As I've said before I think that ego plays somewhat of a role in asking for help and if you do ask for help then it can be a blow to your ego depending on how the help is explained. It's why men don't like to ask for directions when we're lost.
Referring to “Choose the Right Form of Reference,” I wonder about how you can use reference documentation to reach all users? I know Barker says that advanced users will only spend a short time with the document, but I wonder how much you should include in these documents. Should it just be a “quick N easy” review of what has been covered, or should you give detailed chunks of information that’s just broken up for easy access? What would be the ideal situation for either of these scenarios? I guess I’m back to that impossible to answer question of what does a reader want. Which, as we know, can drive a writer insane if they don’t know when to cut themselves off.
I, too, agree that when the user is apparently more advanced, they tend to head for the reference documentation. And why not? They are already familiar with the more mundane functions of the applicatin they are using, so they would probably only use the documentation if they were stumped.
Although it depends on what I'm working with, in my personal experience I use the documentation any time I'm having trouble. I'm OK with whatever type of documentation is available. The reference-type of documentation is probably the most familiar type to me, because I'm kind of "old school" because I grew up with paper manuals to guide my computer learning.
I also use reference documentation whenever I'm having problems that I want to overcome when doing a task. I think alphabetical organization is really helpful when trying to find a specific topic to get help with, and at first I was thinking that I'd prefer that organization. But after reading the section on menu-by-menu organization, it really made sense to me and seems like it would be really helpful in software that has tasks laid out in a specifi order.
Most frequent users of reference materials would consider themselves to be experts with the software in question. The users are familiar with the software, know most of its functions, and are only using reference material to look quickly for one specific piece of information. I would assert, then, that these expert audience members would be highly resistent to changes in the method of presentation. What I mean is, they would benefit the most from conventional methods of documentation. They expect to find something somewhere, and if they don't find it there, they will become frustrated.
Last year I took a tutorial on using Microsoft FrontPage, and it utilized a split-screen of instructions and video animation to demonstrate basic tasks to me. That type of presentation might make learning a program interesting to a novice like me, but to an expert, video animation would appear superfluous and unnecessary. For reference materials, they'd prefer to stick to what they know, so it's best to give them what they know.
This chapter is definately tied in with audience. It stresses the importance of knowing your audience and how to write to best serve them. Most users of reference documentation know enough about the program to do more advanced techniques that require additional help. They need help with procedures that need more than a click to be accomplished.
Short and to the point, best sums up what writing support references. Support references come in to play during the usage of the software. Keeping that in mind the writer needs to know that the user understand the basic functions but has come to a situation that they are unfamiliar with and they only need enough to keep them going, and no more.
I think the goal of "Find the most convenient way to lay out information, and then copy it" is a pretty solid plan.
Post a Comment
<< Home