Writing to Support – Reference
Barker discusses the third level of the levels of support, reference documentation, also known as support documentation. Barker defines and explains the purpose for the three types of reference information:
Appendices: which allow the documenters a place to put all the highly detailed, technical information that the technical users would want to use in the workplace. The appendix is relevant and useful but may not be essential to all users. Some examples of items in the appendix are:
- Error messages and explanations of how to recover from them.
- Filenames and extensions of files associated with the program.
- Troubleshooting tips.
- Matrixes of compatibility with other programs.
- Charts showing program key combinations.
- Printer driver charts showing capabilities with various printer brands.
- FAQ.
Update Information Sections/Readme Files: Consist of text files that accompany programs either with an additional disk or download from an internet site. They serve the purpose of informing the user of new information, installation details, last minute changes, new features, etc.
Job Aids: also known as job performance aids, are shorter forms of reference documentation that include keystrokes, definitions, brief processes, command summaries and other information useful to users. The purpose of the job aid is to provide useful information at the point of need. They consist of a number of forms such as; keyboard templates, cheat sheets, laminated program cards, quick reference cards, and other forms. Another variation of the job aid is the innovative forms: Flipcards, the purpose of the flip card is make it easier for the user to simply flip through the information he or she is searching for.
Innovative Forms: Flipcards This section Barker also discusses as an easy to follow format it is technically classified with the job aids. The flip card is valuable because:
- Easy to read
- Contains a surprisingly large amount of information
- Colored headings
- Unique and interesting
- Affords easy access to information.
Barker also discusses the importance of what to include in your reference guide, he breaks up the reference specifications into three main groups:
- Commands: refers to all the instructions the user uses to make the program work.
- Information about the commands would include:
- Meanings of special function groups
- Explanation of set commands
- Definitions and use of format commands
- Special procedures for using utilities
- Explanations of toolbars
- Definitions of macros
Interface Elements: Refer to the parts of the screen that the user sees and has to manipulate in order to use, these include:
- Explanations of menus
- Definitions of keys
- Labels of screen regions
- Explanations of rulers
Definitions of Terms (Glossary)
- Concepts that underlie the software
- Terms relating to the subject matter of the software
Barker also discusses the importance of organization either alphabetical or menu-by-menu. Menu-by-menu may have more advantage because the user is used to seeing that format. He also states that you should explain to the user how and when the reference guide should be used. It is different from teaching or guidance level of support, it is there to inform the reader not to give a “how to”.
3 comments:
I found that I could really relate to Barker's discussion of job aids. At every company I've worked for, we've had some sort of job aid. Most of the time, it was something put together by the company or specific department. These aids helped out with certain functions that I didn't do all the time, but still needed to know. It was nice having a reference at my desk so I didn't always have to go ask someone else or waste time searching the help options. I never really thought about how valuable these aids were until I lost one. They help out a lot with company productivity, and they are definitely worth the time and effort of creating them.
I would be interested to know more about how to develop FAQs. In their truest sense, I would think that they would have to be a living document, to which commonly-asked questions are continuously appended. Of course, not all documentation works this way, and if the software was new, users would have to use it in order to come up with questions. I suppose there are many different approaches.
I find it as difficult to write FAQ's as it is to write instruction manuals because you have little to no reference of how much knowledge the user has.
Post a Comment