Reference documentation, or support documentation, are the look-up and help parts of a manual. They should be organized in a task-oriented manner, not just alphabetically. When designing reference documentation, it is important to consider the correct form and organization method, as well as the user's needs.
Choose the right form of reference
Different forms of reference documentation include appendices, Readme files, job aids, and innovative forms.
Appendices are sections of a manual containing detailed, technical information. Sections may include error messages, filenames, troubleshooting tips, compatibility information, key combination charts,printer driver charts, or frequently asked questions.
Readme files are text documents containing important initial information, including installation details or tips, information updated or added after the manual was created, new features in an updated program, revision histories, errors, file descriptions, content of directories, and compatibility requirements.
Job aids, or job performance aids, are shortened documentation that help users with basic knowledge to perform tasks more efficiently. Job aids may include keyboard templates, cheat sheets, laminated overview cards, or quick reference cards.
Innovative forms are documentation that are presented in special formats, such as foldouts, posters, and flipcards. The advantages of special formats like flipcards are that they improve readability, contain a lot of information, make information more accessible, and use elements like color to help locate information.
Decide what to include
Reference documentation should include three types of content: commands, interface elements, and terminology.
Commands are the instructions used to work with a program. These include meanings of special function groups, explanations of set commands, definitions of format commands, instructions for using utilities, explanations of toolbars, and definitions of macros.
Interface elements are parts of the screen that are used to interact with the program. Information aobut interface elements may include explanations of menus, definitions of keys, labels of screen regions, and explanations of rulers.
A glossary defines terms used in the manual. Glossaries may defines terms that relate to the software itself or to the subject addressed by the software.
When developing reference documentation, writers should also consider the content to include in each reference entry. They may include conceptual information, structural information, how-to information, or technical information. Conceptual information explains the term and its function. Structural information explains how the term relates to other terms. Technical information describes the programming information related to the command. The content of each reference entry should be based upon the user's needs.
Establish a pattern
Whatever the content of reference entries, the same pattern should be used for each entry. This helps the user to become familiar with the format. Topics included in patterns of reference entries include definitions, explanations, examples, step-by-step directions, and warnings.
Organize the reference section
Decide what organization to use on your own. Make sure to decide something that supports the overall task orientation of the manual. There are two basic choices to use to accomplish this: alphabetical and menu-by-menu.
Alphabetical
This format divides the commands into groups based on the beginning letter of the command, in alphabetical order. You can choose to do this by specific term, or by sections of commands. However, if you choose the latter option, the question becomes how to organize the sections: simple-to-complex or more abstract and concept-oriented.
Glossaries are a type of alphabetical reference, which users appreciate because of the virtue of predictability. Using a glossary emphasizes features over functionality. The glossary also helps the writer by helping to make sure all the features are explained.
Unfortunately, the drawbacks for alphabetical organization outweigh the advantages; the main drawback being that the format doesn’t support the task orientation of the manual.
Menu-by-Menu
This format sets up the references by menus. This allows the writer to arrange the documentation as it appears on the main screen or the menu bar. The organization is almost self-explanatory: a main menu, secondary menu, etc. This format provides a reinforcement of the task orientation between the documentation and the screen.
Show how to use the reference information
In most cases, the reference information shouldn’t include information on how to use it. With multiple, elements, however, the user should be shown the path the writer intends to follow. Usually, this is done with an introductory paragraph that states:
- Who should use the information
- How the writer organized the information
- Elements of each entry
- Relations to other sections of the document
Discussion
Reference documentation is designed to function on the support level of task orientation. There is very little “how-to” information included in this type of documentation. In fact, reference documentation establishes the least engaging relationship with the user.
Understanding the reference user
Reference users do not like to waste time looking things up in help functions or manuals. They also dislike having to leave a screen to search for their information. Well-designed documents will cater to the values of efficiency and immediate usability for these users. As a writer, be sure to establish a pattern and follow it. A good rule to follow: generally, the more structure there is in the information, the more usable the entries are within the document.
Understanding a reference entry
As the writer, look at the idea behind the repeated categories, column heads, or other user-oriented reference elements. These work for the user because each one answers a question the user might have about a function or command. Keep in mind that the elements of a reference entry respond to the needs of the reference user. Each entry should have the following:
- Access information
- Function definition
- Associated commands
- Qualifications/special cases
- Tips
Try to answer these questions for the reference user:
- How do I get to the function?
- What does the function do?
- What other commands do I need to know about?
- When can I use the function?
- How do I use the function well?
These elements should do much of the work of establishing the task orientation of a manual.
Please check pages 112-113 for a checklist to evaluate efficiency for a reference document.
(Submitted by Team 1: Beeman/Xiong)
12 comments:
This chapter was very instructional for me. It made me think of the ways I've used reference materials for different software programs, and what I've found useful (or not so useful) when I've tried to locate information.
Barker notes that users don't read reference sections completely, so the organization of information is extremely important. Patterns do help users know what to expect. In addition, when reference documents mirror the structure of the software program, they can reinforce one another.
The illustrations provide good examples of the different approaches to reference documentation.
Of all the forms of documentation, I am most comfortable with reference documentation. I have used countless programming reference manuals, which come in extremely handy when you are programming in a language that you don't have much experience in. Programmers are often expected to write some code in languages that aren't primary for them, but they usually don't need lengthy tutorials to get going. Most programming languages are very similar--the biggest differences between many of them is the syntax and built-in functions that are part of the language. For these, a good reference manual is perfect.
An essential element of a good programming reference is a fairly thorough example section. It's one thing to see the semantic meaning of a function, but its another to see a demonstration of that function's capabilities and what it can do you you. This is where task-oriented writing is so important. Give the user a real-world example and the reference material will be of such higher value.
Thank you for the fine summary. Like most of us, I have been the victim of poorly documented software and applications. I liked the chapter's discussion of the various forms of reference documentation and the benefits and negatives of each. I'm a strong believer in the effectiveness of quick start guides because they offer the user a chance to skim information and jump in to the application or task immediately. As the author points out, many users dislike certain forms of documentation, but love documents that are nicely illustrated and allow users to get up to speed quickly.
This chapter was packed with information. It was interesting to see how the author breaks down reference documentation into neat and tidy organization. Too often, the user of a software program realizes the documentation is terrible, but really can’t pinpoint why that is. The advice in this chapter will help the writer to avoid unorganized documentation.
I most appreciated Barker’s advice to “establish a pattern.” Familiarity within the documentation gives the reader/user the edge on comprehension. When the user knows that a particular convention means something, then the ability to quickly work through a complex procedure becomes that much easier. While Barker never says it directly, it seems to me that the establishment of a hierarchy of tasks in documentation will be most helpful. If the writer can establish a pattern that the reader easily follows, the ability to find information quickly and efficiently is then established.
I'm a big fan of flipcards. I like being able to find the information that I need quickly, and having it already in eyesight while working on a computer is a bonus. I have used them in a couple different jobs I've held for quick keys and information that is useful that people don't necessarily memorize. I think they are a great reference tool.
This chapter was very informative, and contained a lot of useful, practical information. I think the focus on task-orientation is very logical and wish that more documentation was written in this way, after, like most readers and users, having had not-so-pleasant experiences with manuals and help. In particular, I found the section on choosing the right form of reference to be informative. I think that the illustrations Barker chooses to include are almost essential to the text because sometimes the amount of text is a little overwhelming, and it can sometimes be difficult to understand what he is describing.
The main idea that I took from the summary of chapter 4 is learning about different forms of references. I plan on using this chapter as a guide when completing projects for this class or if I need to write a software document in the professional context. Most of the information seemed common sense thou it is nice to know about forms of reference and they advantages.
I have used some of these reference forms such as appendix and reference sections with various elements (how-to information, commands etc) previously as a software user. This chapter not only expanded my knowledge on the forms of references but further emphasized the importance of organization in technical writing. I do like to use organized documents and I will take that into consideration when creating one in the future.
Also I think that task-oriented documentation approach determines form of reference documentation, levels of detail in each entry and how the reference information will be used. The task, audience and needs of the organization once again will drive the decisions of technical writer.
I am really new to this, and to be honest I didn’t realize there were so many types of documentation--or perhaps I just never really thought about them. As I continue on in the course, I have started paying more attention to the documentation I use for different products. Such as, the other day I was looking at the documentation for the DVD player/recorder at work. Suddenly, I was aware of what parts I would change and what the manual was really missing. We (or I should say, the general public) do really take “good” documentation for granted, but it is noticeable when it isn’t so good. Overall, I enjoyed learning more about the different types of documentation in this chapter.
I didn't originally think I had much experience using reference documents. I only know I expect to be able to utilize a reference section if necessary. But many of the textbooks I use in my classes have excellent reference forms.
In software application texts, a common practice is for authors to place a perforated or foldout "cheat sheet" for commonly used features in the back of a textbook. Another helpful feature in texts I use is for a simple list of concepts covered at the end of each chapter so students can go back and review how to perform a task. Finally, nearly every textbook used for Microsoft applications include a section on how to use the Help feature. So, in one course, numerous reference forms are encountered.
This chapter broadened my knowledge about reference documents and considerations to make when designing/writing the documents.
I've never considered how the three different "levels of support" that are described in this book apply, in general, to entirely different users. I had a kind of "aha" moment when reading through this chapter, although to, most of you this will be old news. Teaching for beginners, guidance for more experienced users, and reference for the most experienced users. It's a progression of needs being filled in a organized and systematic way.
I use mostly Microsoft products in my work and consider myself to be a fairly experienced user. I turn to reference materials only when I can't figure something out on my own. His description of the reference user's needs is right on with what I'm looking for. I don't like to waste time looking things up. I'm happy when I can find something quickly and it helps me do what I want to.
I need and love glossaries and references at the end of the book, but I always took them for grated, up until I began this program and now understand how much work it really demands to put a usable and helpful glossary together. I tend to be an info-pack rat, so my glossary would probably be in danger of being too exhaustive and becoming less usable. To be selective of the right entries requires sensible approach and a lot of practice. Also, one needs to know his/her audience and maybe get some feedback from the end-user before submitting final draft/selection.
Post a Comment