How to Use References

1
How to Use References

• Chapter 4

2
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

3
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.

4
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

5
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

6
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.

7
Establishing a Pattern

• Have you established a pattern for each reference
  entry?

8
Organizing the Reference Section

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

9
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