Establishing a documentation process

Subject: Establishing a documentation process
From: geoff-h -at- MTL -dot- FERIC -dot- CA
Date: Tue, 19 Mar 1996 12:38:57 -0600

Some time back, I asked for help in imposing a structure on
our current chaotic process for producing documentation for
upcoming software. Here's what we've come up with so far
(feel free to add to this summary):

0. Before starting
Try to develop a close, amicable working relationship
with the other team members: you'll be prevailing upon
their kindness for some time, and things will go much more
smoothly if you start out amicably. Even if you can't
develop this sort of relationship (e.g., you're working in
another city), try to keep in touch about more things than
just work... this is what builds successful and mutually
enjoyable relationships.
Define your audience, and their needs, explicitly and
carefully, before you start. (In _our_ context, this has
already been done surprisingly well, but we have a small,
very homogeneous captive audience that we've worked closely
with for 20 years. Very few development projects arise in
such a context.) The definition process may lead you, for
example, to create an exclusively reference manual, or an
exclusively task-based manual. The process may also lead
you to include additional material such as indexes, system
requirements, and contextual notes (e.g., lists of
Create some simple (i.e., not a burden on anyone) but
effective method of learning about changes in the software
so that you can account for them in the documentation. This
is a great time to educate your fellow team members about
the need for interaction, and what happens if the
interaction doesn't occur.

1. Define product features
Verify that you really know what your users will do
with the software (i.e., a task analysis) and that you
understand their language and work habits as well as you
think you do. (This is a good time to create a docs style
guide!) Specifically define the audience in terms of tasks
and how they talk about the tasks, and understand why each
feature is useful to this audience. Informal (e.g.,
spoken), tacit definitions are insufficient.
Try to identify subject matter experts for each
component of the project, and persuade them (via the
Management "big stick" approach if necessary) to
participate actively in reviewing your material. If you
can't obtain access to subject matter experts, identify
other individuals (e.g., the product's users) who can
Create a formal documentation plan, including any need
for online or printed tutorials. Define as much as you can
explicitly, in writing, and ask all participants to review
the final specifications that you produce. (Ideally, get
signoffs from the various authorities involved.) Don't
forget that there may be internal (e.g., corporate) and
external (e.g., ISO, government) standards that you must
meet, and you should explicitly address how you'll do

2. Create a mockup of the user interface
This is a great time to perform some pen and paper
usability testing if you can't do the real thing. Any
little bit helps at this stage, because mistakes that you
make now will come back to haunt you later. It's also a
great way to plan your online help. This is an ideal time
to produce a documentation plan that defines all
deliverables (e.g., each component of the docs), the
assumptions underlying each one, and the consequences for
missing deadlines for each deliverable or producing an
inadequate deliverable.
It's helpful to keep a binder full of printed
screenshots for each screen, and update each printout as
features change (particularly between versions). You can
produce final screenshots once the software is frozen
(see below), but you must verify these shots against the
final documentation (e.g., no new buttons added since
last screenshot) and the final software (e.g., no
last-minute changes to interface). Developers often
create small cosmetic changes without informing you, and
you can greatly disconcert users when the screen differs
from the docs.

3. Begin documentation of features and interface
You can't finalize anything and identify when you can
deliver it until the product is stable: "The doc clock
starts when the UI is frozen" (attributed to Peter
Hartman). Our very own Sue Gallagher adds: "The
documentation will be ready for the printer two weeks
*after* UI freeze", a tough standard to meet but worth a
try. Depending on how stable things are at this point, you
may not be able to do more than create a good outline and
some background information ("what you can do with this

4. Freeze features/interface (if not already done)
We've seen lots of plaintive postings about documenting
a moving target; the rule of thumb seems to be that the
"freeze" may not occur until moments before the product
ships, no matter how well you plan. If you can freeze the
product early on, do so. If you can't, at least try to
establish some method of coping (e.g., clear notification
of any last-minute changes at the stage where the changes
are _proposed_, not after they've been implemented). This
_will_ require strong support from the project managers.
Recognize that all freezes must be followed by thaws;
for example, "beta testing" (see below) may well lead to
significant changes that undo the freeze. (Get involved in
the analysis of the results of the beta testing so that
you'll know what changes will result from this analysis.)

5. Complete the documentation
In some cases, you may not reach this stage before beta
testing begins. Try, but don't be disappointed if it
doesn't happen. If the software changes at all, the
docs must certainly change.

6. Begin beta testing
Make sure that some form of the documentation gets
included at this stage, since it may be your only chance
for feedback from your audience. Carefully define what you
expect the testers to focus on. If you want them to focus
on the typography, fine, but if not, tell them to ignore
the type. In some cases, providing a test script of some
sort is invaluable.
Resources permitting, don't let beta testing be a
purely passive process. As much as possible, stay in touch
with at least a subset of your beta testers, and probe for
specific points. Pursue anything interesting that may lead
you to change your documentation and development strategy,
in whole or in part.

7. Revision and final distribution
Some changes will inevitably occur after beta testing.
Formally identify these changes, and how you'll deal with
them... then follow up to make sure your response is
adequate and that you have implemented it correctly. (You
may have to do triage: items that you must address
instantly, items that you'll address if you have time, and
items that can wait until the next revision.) Finally,
conclude with some sort of reward for yourself and your
teammates... you've earned it!

Several folks suggested JoAnn Hackos' book "Managing Your
Documentation Project" (John Wiley and Sons), which has
also been highly recommended in various reviews. The
skeleton that I've presented in this summary is well
enough clad for the purposes of modesty, but the bones are
still plainly visible in places. JoAnn's book should
provide the necessary fig leaves.

Thanks to the following individuals for contributing
invaluable advice: Art Elser, Sue Gallagher, Bonni Graham,
Sue Heim, Donna Menk, Robbie Rupel, Emily M. Skarzenski,
Bill Sullivan, Chris Thiessen. Many other list members have
provided information on related points over the past
several months; thanks to all of you too!

--Geoff Hart @8^{)}
geoff-h -at- mtl -dot- feric -dot- ca

Disclaimer: If I didn't commit it in print in one of our
reports, it don't represent FERIC's opinion.

Previous by Author: Re. Copyrighted e-mail
Next by Author: Re. Quick and dirty indexes
Previous by Thread: Re: Establishing a documentation process
Next by Thread: Justification

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

Sponsored Ads

Sponsored Ads