How to Use References Chapter 4

Reference Documentation This is also referred to as support documentation, includes all the look-up sections and elements of your manuals and help. It takes forms like: Command descriptions Menu overviews Lists of definitions Function descriptions Examples Error messages

Types of Reference Documentation Readme Files – Text files that accompany programs on the distribution disk or come when you download the software from an internet site. It contains installation details, last minute changes that are not included in a manual, new features in a recent release, file descriptions etc. Job aids – These are shorter forms of reference documentation that includes definitions, brief processes, command summaries etc. These are for people who already have basic training with the software.

Choosing the Right Form of Reference Have you chosen the right form of reference to match your users’ needs? Reference section (tables of dates, definitions, and command descriptions) Quick reference (card, booklet, brochure) Appendix (tables, messages, troubleshooting) Update information/ ReadMe files (disk file containing update highlights) Job aids (reminders, command lists) Innovative forms: flip cards

Deciding What to Include in the Reference Section Which of the following elements meet your users’ needs? Commands Interface elements Definitions Concepts Relationships among commands How-to information Technical information

Deciding What to Include in Each Reference Entry Identify which of the following elements you want or need to include in each reference entry to meet your users’ support needs. Definition: Tell what the command or function does. Explanation: Tell how to apply the command or function. Example/syntax: Give an example of the command or function in use. Step-by-step: Present abbreviated steps for using the command or function. Warnings/cautions: Let the user know what problems might arise.

Establishing a Pattern Have you established a pattern for each reference entry?

Organizing the Reference Section Which of the following organizational patterns do you intend to use? Alphabetical Menu by menu

Showing the User How to Use the Reference Information Have you written a section that tells the user the following things? Who should use the information? How you organized the information The elements of each entry Cross-references Sample library entry