Re: Writing User Guide for code

Subject: Re: Writing User Guide for code
From: "Wing, Michael J" <mjwing -at- INGR -dot- COM>
Date: Mon, 2 Dec 1996 14:20:47 -0600


I view this documentation task as two separate entities. The first
entity is the user information; the second is the reference information.
My beliefs are that the user information should be presented in
functional groups. Therefore, the commands could be grouped by
common-functionality (file manipulation, image display, text editing,
and so on). The reference information should be a command-by-command

To me, the user is trying to determine what they can perform with the
commands, the sequence in which the actions must be performed, and the
overall flow needed to produce a desired results. The reference guide
would give the command-by-command details (argument list,
required/optional, and so forth). Often, code is documented only as
reference material (dictionary style) leaving the user to determine what
needs to be done first, second, . . .

For example, if the syntax involved database manipulation, functional
groups could be opening, creating, and populating the database; data
extraction; error trapping; and so forth. The information in this guide
would be more holistic than the reference guide. That is, the "what are
my functional groups?", "how do my functional groups interact", "what do
I perform first?", "are there prerequisites?", and "what are my
variations in performing these tasks?" questions are addressed in this

The user documentation would also illustrate a through process. That
is, it would only cover the syntax necessary to complete each functional
task (such as creating a database and defining its table and field
structure). If information non-vital to performing the functions (such
as displaying the database version) is available as a command, quickly
describe its purpose and syntax, refer the reader to the reference
guide, or both (with the reference guide elaborating on the command).
This should be done to keep focus on the functions and not lead the
reader down a side path.

The reference guide would supply shorter segments of code. Just enough
code to illustrate the use (and variation of use) of the command at
hand. In this guide, the syntax elements can be explained in detail.
To me, the user reads the User's guide to become familiar with the
sequence and end goal of the code and reads the reference guide (as
necessary) for each command as they program.

Mike Wing

| Michael Wing
| Principal Technical Writer
| Infrastructure Technical Information Development
| Intergraph Corporation
| Huntsville, Alabama
| (205) 730-7250
| mjwing -at- ingr -dot- com

Previous by Author: Re: Point zero or just point?
Next by Author: Re: Re[8]: Killer Language
Previous by Thread: Writing User Guide for Code
Next by Thread: Re: Writing User Guide for code -Reply

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

Sponsored Ads

Sponsored Ads