TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
Keith;
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
listing.
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
documentation.
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
| http://www.ingr.com/iss/products/mapping/
| Intergraph Corporation
| Huntsville, Alabama
| (205) 730-7250
| mjwing -at- ingr -dot- com
