Re: Documentation Management?

Subject: Re: Documentation Management?
From: Robert Plamondon <robert -at- PLAMONDON -dot- COM>
Date: Thu, 10 Apr 1997 07:45:36 -0700

Jennifer Kraus writes:

>I'm especially curious as to the review process (engineering, >technical, etc): how do you assure that the reviewers REALLY review >the document, and don't just sign off on it without reading it? Do
>you give multiple copies of a single document to several reviewers
>at once, or do you send it to the first person, make changes, send
>it to the second person...etc. Do you provide a checklist of things
>to look at?

The review process is really very simple. Just follow these

* Go after the appropriate managers and extract a promise that
their groups will review the documentation thoroughly and on
time. If you don't get it, inform your manager that the
promised corporate commitment to adequate documentation is
not yet in place, and that you will necessarily be shipping
draft-quality documents. Creating an environment in which
work can be done properly is management's job. While there
are sneaky things you can do to work around passive management,
I sometimes wonder if they're worth it. (As a matter of
productivity, would the readers be better off if I spent
inordinate amounts of time chasing down a few errors, or if
I did some new work? With sufficient barriers to the review
process, one can reach the point where it's more efficient
to have errors pointed out by the users than by the developers.
This can be true not only from the writer's point of view, but
by the user's, as well.)

* Never, ever let two people mark up the same review copy.
You don't want anonymous markup, since a large fraction of
markup makes no sense -- you need to track down the reviewer
and find out what he meant. Also, gang-markup tends to be
extremely sloppy, as no one takes responsibility for their work.

* Break the document up into assignments (of, say, a chapter each),
and put one expert in charge of reviewing each assignment. If three
people are asked to review a chapter, each will assume that one
of the others will do it, and it won't get reviewed. If the
review copies each have an assignment sheet, and the reviewer
sees his name as the lone reviewer of chapter 3, and he sees
his boss' name on the CC: list, he is quite likely to actually
do his job.

* Certain crucial bits, such as the corporate address and phone
numbers, or the pinouts on an integrated circuit, should be
reviewed separately. I was constantly blindsided by phone number
changes at overseas distributors (and similar problems), until
I started handing pages with this information to the secretaries
who dealt with them, at which point my problems disappeared.
Similarly, I don't trust design engineers to actually know the
pin assignments and physical dimensions of their own chips. The
manufacturing engineers are far more definitive about such things.
So don't be afraid to hand out an assignment that consists only
of a page or two.

* Don't give much time for a review. I've found that, the longer
the review period, the fewer copies I get back. Or maybe it
just seems that way. If you give smallish assignments, give
a deadline of, say, a week, and send out several reminders
before and during the review period.

* If the review copies don't come back, ship regardless. My
personal preference is to put the word "DRAFT" on every page
of a document that hasn't been thoroughly reviewed, both to
warn the reader and to shame the reviewers. This also has
the pleasant effect of driving the sales and marketing managers
insane. Redirect them to the office of the offending engineering
manager, and you will hear your own points made with greater
force and in more colorful language than when you presented them
yourself. (Few people follow this strategy, but I'm very fond
of it. You don't allow your documents to be held hostage by
uncommitted reviewers, you're honest to the readers, and the
word DRAFT on every page really annoys upper management, which
is usually perfectly willing to accept the answer of, "if they
did an honest attempt to review the document, I'd take it off
in an instant.")

* Never lose track of the fact that the reviewers don't work for
you. You can't have a moral obligation to extract a first-class
review from the reviewers if you have no means to do so. You
might as well take responsibility for preventing earthquakes in
San Francisco. You do what you can to increase the likelihood
of a good review, but try to avoid the stress and martyrdom that
many people pile onto this step. If the reviewers do a crummy
job, the document isn't going to be as good as it ought to be.
Ship it anyway, but don't lose sleep over it. Try to convince
management to do its job, of course, but don't worry overmuch
about inherent flaws in the system that's been imposed upon you.

-- Robert

Robert Plamondon, High-Tech Technical Writing, Inc.
36475 Norton Creek Road * Blodgett * Oregon * 97326
robert -at- plamondon -dot- com * (541) 453-5841 * Fax: (541) 453-4139

TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
Search the archives at or search and
browse the archives at

Previous by Author: Re: Design Decisions
Next by Author: Re: Editorial Latitude
Previous by Thread: Re: Documentation Management?
Next by Thread: Photoshop and Illustrator discussion lists

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

Sponsored Ads