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:Establishing a documentation process -Reply From:Bill Sullivan <bsullivan -at- SMTPLINK -dot- DELTECPOWER -dot- COM> Date:Mon, 11 Mar 1996 16:51:51 -0800
The process, as you roughed it out, goes:
1. Define product features
2. Create mockup of user interface
3. Begin documentation of features and interface
4. Freeze features/interface (if not already done)
5. Complete documentation
6. Begin beta testing
7. Revision and final distribution
-- Somewhere in there, probably under 1., I would add:
A. Define users.
B. Define user concerns: By intuition, by interviewing sales staff,
by interviewing tech support, by interviewing anyone else, by talking
to users yourself (create a focus group maybe?), by working with
specialists in usability.
C. Determine user questions when they refer to manual.
D. Address user questions, needs, concerns.
For some user groups and situations, a kind of reference guide to all
of your menus and menu operations would be right. For others, you
might justify a task-oriented approach. Getting your manual right
with your readers is the biggie. Here also are some miscellaneous
If users are going to have to install the program, a list of System
Requirements would be in order.
I would also make a determination as to whether an index would be
appropriate. That would come after item 5 on your list. Just before
item 5 on your list, you better be making some decisions about type
styles. Get a cover page and title page going. Figure out what you
want in your headers and footers, left and right.
Step 3 might include a list or working list of figures and perhaps
tables. If you decide to go with screen captures, you will want to
be sure you have all the right tools.
Somewhere early in the process, it would be a good idea to determine
who your subject matter experts are and what your review process will
be. You could have a rough outline of the manual and a cast of
characters pencilled in beside each chapter, the characters being the
technical people you can interview. It helps to have all of the
management muscle you can muster. Nobody should be too busy to work
with the tech writer. After you work out your drafts with your
technical collaborators, you should know who the reviewers will be:
Engineering, software development, company president, manufacturing,
technical support, whomever.
Other than that, there's not much to think about.
bsullivan -at- deltecpower -dot- com
San Diego, California