Re: Documenting A Moving Target

["Susan W. Gallagher" <sgallagher -at- EXPERSOFT -dot- COM>]

At 4:16 PM 2/20/96, Karen Gwynn/Datatel wrote:

>Problem: I am trying to document a product that is still being developed, not
>just tweaked. By this I mean, something that I documented on January 31, now
>works differently. I think the change to my doc is relatively minor, but the
>simple (ha!) fact that I have to review at least two chapters to make sure my
>explanations are right and to recapture at least three screens is enough to
>drive me over the edge. I've got three manuals and online help to finish by the
>end of July and the programming is going on in one form or another until pretty
>darn close to my deadline.

>HELP! What do other people do? Do other software companies build in time at the
>end of the development cycle for doc to catch up? Whose responsibility is it to
>notify doc of all these changes as they occur (that's the other thing; I
>happened to find this item, no one told me of the change).


Changing a tire on a moving vehicle, are we? You're not the
first to try, Karen -- and you won't be the last, either. This
is an ongoing problem in the software industry.

First, the only times the documents need to be absolutely accurate
are beta release(s) and at the end (first customer ship/general
availability). Trying to keep up with things all the time is a
waste of your time -- although I've worked with project architects
who insisted on it. Don't stress that the docs are out of sync with
the product.

Second, try developing the conceptual material first, since this
is least likely to change from build to build. You can leave holes
in the doc where procedural and field-level information will go
and document that when the product is more stable.

Third... I don't know *why* some developers have the impression that
we look at every dialog box every day. You look at it, you doc it,
you're done and don't go back, right??? You can request that the
programmers send change notifications each time they change some-thing
that affects the user interface. Oh, they'll forget a lot -- and when
they do remember, they'll send you messages like "I changed the
stamafrage dialog" -- [HOW???? Did you translate it to Russian???]
No, they won't tell you how, but at least they'll let you know where
to look for changes.

And, finally... When they ask you when the documentation will be
ready to send to the printer, answer, "two weeks after the UI
freezes." There's plenty for the developers to do... bug fixing,
stress testing,... They'll keep busy while you catch up. (Just, if
you give 'em the "two weeks" line, make sure you make the deadline!)

FWIW




-Sue Gallagher
sgallagher -at- expersoft -dot- com