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 -Reply From:Bill Sullivan <bsullivan -at- SMTPLINK -dot- DELTECPOWER -dot- COM> Date:Wed, 4 Dec 1996 12:23:58 -0800
> 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?"
Consider the product and how it will be used and by whom. Is the
product a major tool for word processing or spread sheets that will
be used every day for a broad array of tasks by users with various
levels of expertise? Is the product used every day for just a few
tasks by users who know their jobs? Is the product to be used only
occasionally by computer-smart users who may forget how to use the
product between uses?
For whatever reason, it sounds as if you have settled on a
task-oriented, how-to sort of manual. The other choice would be to
develop a product reference based on each menu and its menu options.
In the one type of manual, you write to user situations and problems.
In the other, you write about the product. You will have to decide
which approach makes more sense in terms of serving your users,
making your manual more valuable, and so forth.
Don't over look your Table of Contents and Index tools, and the
possibility of getting the best of both worlds. If you choose to
make your manual into a reference guide to each menu and menu option,
you can always write "How To" headlines under each and add them to
your TOC. For example, in your File Menu section, you would have a
Save subsection, and you could have a How To Save a File section
under that.
Assuming it would not be too cumbersome, you could organize your TOC
so that all of your "How Tos" were at the same level. Users could
scan the TOC to find the procedure they needed to find.
I would also give plenty of thought to organizing my index so that it
would make the manual a combination how-to-do-it manual and reference
guide.
