Writing User Guide for Code

Subject: Writing User Guide for Code
From: Alisa Dean <Alisa -dot- Dean -at- MCI -dot- COM>
Date: Mon, 2 Dec 1996 12:07:00 -0700

On November 29, Keith Jeremy Posner writes:

>---> Anyway, to cut a long story short, I'm trying to outline the user
>guide for this product. Common sense and experience tells me that I
>should list real world tasks, ie things the user actually wants to do
>with this product and then the content of each task will give examples
>of code (i.e. specific syntax structures) that will achieve this task.
>Can anyone suggest an alternative approach to planning a user guide for
>this type of product?

Here is a general outline that I have found to be very successful for
user manuals:

Ch 1: Introduction
- Brief introduction of company and product (mainly marketing-type
- Summary of contents of manual
- Description of special notation/terminology within manual - such
as bold text indicates names of on-screen items, courier font for typed
input, maybe include brief glossary

Ch 2a: (If necessary) Installation
- Describe very specific step-by-step installation procedures. Include
caveats, safety notes, possible problems and solutions, and whatever
else the user needs. If possible, try doing an installation yourself
to catch those gaps. Note: This section can be moved to the back of the
manual since, hopefully, it will be used once in the life span of the product.

Ch 2b: Description of the Product (parts/buttons/menus)
- Provide an item-by-item identification and description. Do not
describe use or procedures. Refer as necessary to chapters 3 and 4.

Ch 3: Concepts/Theory of Operation
- Discuss how the product is used, special processes, interrelationships,
and so on. Use a narrative format, graphics, whatever, to explain
how the product is used. Break into subsections according to topic.
Note: Typically, this chapter will be read when the user first receives
the product or the user is trying an unfamiliar a new procedure.

Ch 4: Common Procedures
- Create a set of step-by-step procedures that the user would commonly
use. Test for accuracy. Allow user feedback to update/add to set.
Do not describe concepts here - they should have been discussed in
chapter 3. Cross-reference as necessary. Note: The reason for no
discussion is that the user should be able to just step through the
procedures without being interrupted with paragraphs (or pages!) of
descriptive text. Additional note: Once the product is installed and
the user is relatively familiar with it, this chapter will be the most
used chapter. If possible, create a quick-reference card with the
most commonly used procedures that the user can remove and use separately
from the manual.

Ch 5: Troubleshooting
- Provide a list of symptoms, probable causes, and suggested corrective

I have used the above outline in almost all of my user manuals very
successfully. I have customized it to the product and audience (sometimes
rearranging the chapters, adding new chapters, whatever), but I use
this outline as the base to build from.

Hope this helps.

Alisa Dean
Sr. Technical Writer
alisa -dot- dean -at- mci -dot- com

Previous by Author: Re: What Flesch measures
Next by Author: Definitions vs. Glossary
Previous by Thread: Re: Writing User Guide for code
Next by Thread: Re: Writing User Guide for code

What this post helpful? Share it with friends and colleagues:

Sponsored Ads