RE: Which came first: the manual or the help?

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

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

--George Hayhoe (george -at- ghayhoe -dot- com)

George Hayhoe Associates
Voice: +1 (803) 642-2156
Fax: +1 (803) 642-9325

APEX '99 Grand Award for Publication Excellence

Awards of Distinguished Technical Communication
South Carolina/Carolina Foothills STC Chapters
1998-99 Technical Publications Competition

Previous by Author: RE: An Inquiry for Academics
Next by Author: RE: Do Online Books Increase Offline Sales?
Previous by Thread: RE: Which came first: the manual or the help?
Next by Thread: RE: FW: Which came first: the manual or the help?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads