Writing a Reference Guide


Click here to start

Table of Contents

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

Reference Guide

Types of user interface elements

Write about user interface elements

Introduce a dialog box

No introduction

Short description

Short description: Dialog box

Short description: Dialog box

Short description: Menu commands

Complete description

Complete description of menu command


List elements in order

Left to right

By area

By mode, then by area

Writing Exercise

Reference Guide


Syntax summary

Keyboard shortcuts

Values and descriptions

Sample applications

Example of completing a dialog box

File extensions and document conventions

Components and compatibile programs


System requirements

Third-party hardware requirements

Error messages

Reference Guide

Bad error messages

Useful error message

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

List error messages in order

Illogical order

Writing Exercise

Author: Karin Gallagher

Email: kgallag@rpbourret.com

Home Page: http://www.rpbourret.com/kgallag/index.htm