Re: Documentation Management?

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

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
guidelines:

* 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
http://www.pioneer.net/~robertp

 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
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html