Re: How do you track document changes?

[Robert Plamondon <robert -at- PLAMONDON -dot- COM>]

>Software engineers suggest that we conduct a line by line review of changes
>during inspection meetings (like they do when introducing new software
>code).  This is
>time-intensive, and is not appropriate for editorial changes (for grammar,
>clarity, and so on).

>Another suggestion is to review all proposed changes during a consensus
>meeting where everyone signs off on the document at the end of the meeting.
>However, this requires all engineers to review areas of the document which
>may not be relevant or germane to their contribution to the project.

These people are not afraid of throwing labor at a problem!

Here's what we do:

When we get a review copy back, we look at the proposed changes, and,
based on the changes, do what's appropriate (maybe nothing) to the
document.  On the review copy, we put a checkmark next to the copy if
we incorporate it (or something vaguely resembling it), and write "NO"
if we do nothing.  Sometimes we add explanation.

This way, we can go back over the review copy to see if we really saw
all the changes.  Some usually slip by us on the first pass.

When the work is done, we ship the now-heavily-check-marked review copy
back to the reviewer, along with a clean new copy, with a cover letter
asking him to reconcile the two if he feels like it.

This adds only a tiny burden to the writer, who was supposed to go through
all comments systematically anyway.  Marking them as they are dealt with
slows things down but catches a lot of omissions.  It may be a net gain
in time.

We use automatically generated revision bars for reviews, and sometimes
for published documents.  They spell the difference between the reviewer
reviewing the revised sections, and not reviewing the document at all.

"Consensus meetings" imply that the writer is not the owner of the document;
that document ownership is mob rule.  No way.  Also, having a long meeting
with a large number of people, only a few of whom are interested in any
given topic, is the most effective way to waste manpower I can think of.

But, in general, the way you do documentation in a lean-and-mean environment
is to find someone really good, and say, "Make this document happen.  If
you need anything, let me know, and I'll take care of it."

        -- Robert
--
Robert Plamondon * Writer * robert -at- plamondon -dot- com * (408) 321-8771
4271 North First Street, #106 * San Jose * California * 95134-1215

"Just cut a few notes and it will be perfect."