Writing a Reference Guide
Reference guide
Reference guide versus user’s guide
User‘s guide: Conceptual
Write reference material
Write as stand-alone material
Write the same type of information in parallel topics
Be accurate, complete, concise
Three types of reference material
Reference Guide
Write about language elements
Types of language elements
Introduce each type of language element
Describe each element in a similar format
List by type of element, then alphabetical
Writing Exercise
Types of user interface elements
Write about user interface elements
Introduce a dialog box
No introduction
Short description
Short description: Dialog box
Short description: Menu commands
Complete description
Complete description of menu command
Shortcuts
List elements in order
Left to right
By area
By mode, then by area
Appendixes
Syntax summary
Keyboard shortcuts
Values and descriptions
Sample applications
Example of completing a dialog box
File extensions and document conventions
Components and compatibile programs
Graphics
System requirements
Third-party hardware requirements
Error messages
Bad error messages
Useful error message
Types of error messages
Before user makes a mistake
After user makes a mistake
Software gives a status message
How to write error messages
Explain the solution
Refer users to other documentation
Refer users to system administrator
List error messages in order
Illogical order
Email: kgallag@rpbourret.com
Home Page: http://www.rpbourret.com/kgallag/index.htm