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: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
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.
Sr. Technical Writer
alisa -dot- dean -at- mci -dot- com