Re: Documenting A Moving Target

[Ed -dot- Hoornaert -at- VENTANA -dot- COM]

Ah, a topic dear to my heart.

>Whose responsibility is it to
>notify doc of all these changes as they occur

Our programmers are getting pretty good about letting us know of changes
that occur after a certain point in the writing cycle. . . but we had to
train them, with ample help from the head of development.  Ultimately,
though, I'd have to say that it's our responsibility to ferret out the
information we need.  That doesn't mean we'll succeed with every little
detail.  It just means we have to be proactive.

In addition to the other good ideas that people have posted, I'd add
programmer reviews of the documentation.   That's why God invented them
-- to catch things we didn't.  Don't do the reviews too soon; leaves too
much time for more changes to creep in.  Sometimes I've asked programmers
to review a chapter again if it seemed many changes had occurred.
Sometime the programmers, bless 'em, have asked for another review
because they know a bunch of details have changed.

I've been known to have one of my teenage sons keystroke everything in
the documentation, looking for things that have changed.  In addition to
catching discrepancies with a fresh set of eyes, it also gives him a
chance to learn a little about what I do all day long.

Our company has a change request database where bugs and code changes are
kept for approval or rejection.  It can be a frustrating source of
information, but I force myself to peruse it occasionally.

More useful is a one-on-one chat with the programmer.  I'm about to close
this part of the manual; can I do that yet?  Has anything changed that I
should know about?  Is anything likely to change?

None of this is foolproof, of course.  It's an ongoing problem.  And
sometimes a deadline is just plain goofy; the code isn't ready to finish
documenting because the concrete isn't dry yet, so to speak.

>Do other software companies build in time at the
>end of the development cycle for doc to catch up?

We have a de facto (oops, sorry for the Latin) catch up time.  We used to
have a real problem being the last part of the product that was ready to
go out the door. . . until the company improved quality control.  Now the
testers find so many bugs for the programmers to fix that we almost never
end up on the critical path.  The better the testing program, in my
experience, the more time we have to get things right.

Ed -dot- Hoornaert -at- Ventana -dot- com
Ventana Corporation should not be held responsible for my big mouth.