Working with the developers

Subject: Working with the developers
From: geoff-h -at- MTL -dot- FERIC -dot- CA
Date: Fri, 27 Sep 1996 15:15:36 -0500

Misti Delaney asked for tips on becoming part of the
development team. Some time back, I asked techwr-l for help
in imposing a structure on my employer's current chaotic
process for producing documentation for upcoming software.
(No, we're not there just yet, but Management was impressed
that such structure could actually exist!) Here's what we
came up with (hope it serves as a good starting point):

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.

If the product is still changing rapidly when you must
start work, begin by planning and structuring based on your
audience analysis, not by writing. Plan to fill in details
as they become stable.

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 help.
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 this.

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, Richard Mateosian, 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: Speaking for myself, not FERIC.

Previous by Author: Need permission for links?
Next by Author: Machine translation
Previous by Thread: Re: Need permission for links?
Next by Thread: Machine translation

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

Sponsored Ads