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: Which came first: the manual or the help? From:"George F. Hayhoe" <george -at- ghayhoe -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Wed, 15 Sep 1999 10:49:43 -0400
Aoidin Scully asked:
>When you're creating both a manual and online help for an
application, which
>do you create first?
I don't create either of these two documents first. Prior to
writing either a user guide or online help, I prepare an
information plan and content specifications for the entire
documentation set (preceded by several other steps as
described by JoAnn Hackos in _Managing Your Documentation
Projects_).
The information plan for the entire project includes
sections such as Purpose of the Project, Purpose of the
Documentation Set, Usability Goals of the Documentation Set,
Product Description, Audience Profile, Task Descriptions,
User/Task Matrix, Design Implications, Documentation
Strategies and Concerns, Media Selection, Project
Constraints, Client Project and Review Teams, Writing
Project Team, Roles and Responsibilities, and Project
Schedule. This document describes at a high level the basic
organization and content of all the publications that will
be part of the documentation set for a particular product.
The content specifications for each component publication of
the documentation set includes sections such as Goals and
Objectives of the Publication, Product/Process Description,
Audience Profile, Usability Goals and Testing, Publication
Objectives, Publication Organization, Publication Content,
Overview by Section, and Estimated Page and Graphics Count
by Section.
These preliminary planning documents might seem
unnecessary--until you actually sit down and begin
considering the issues that they raise. In the case of a
user guide and online help, for example, answering the
questions raised by preparing an information plan and then
by writing content specs for each of the two publications
will help you decide what information goes in which
publication. These planning documents will also help you
share information between publications in the documentation
set, and they're vital if multiple people will be working on
the project because they'll help ensure consistency of
approach and help you minimize the need for rework.
Once the planning documents are complete, it usually doesn't
matter whether you create the help or the manual first, or
what order the various components of each are written in.
It's also amazing how quickly the publications can be
drafted with these planning documents as guidance.
If you haven't already read JoAnn's book, you should (New
York: John Wiley & Sons, 1994). Even if you don't always
agree with what she says and the approach she takes, it's
helpful to think through a project systematically using her
techniques.
