Writing User Guide for Code

[Alisa Dean <Alisa -dot- Dean -at- MCI -dot- COM>]

On November 29, Keith Jeremy Posner writes:
<snip>

>---> 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
material)
 - 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
actions.

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