Technical review guidelines

["Geoff Hart (by way of \"Eric J. Ray\" <ejray -at- raycomm -dot- com>)" <ght -at- MTL -dot- FERIC -dot- CA>]

Thomas Quine attempted to send his "technical review cover sheet" for
commentary, but it never arrived in any form I could read, and I
suspect most techwhirlers are in the same boat. Thom, you'll have to
send a simplified version of this form directly in the body of your
e-mail message if you hope to receive any decent commentary. You'll
also attract less of Eric's wrath if you avoid sending attachments to
the list in future. That being said, I'll provide some relevant
comments on how to get more effective technical reviews:

First and foremost, send the reviewers the best document you can
send. If they're always fixing typos or swapping words around in
awkward sentences, you're not doing _your_ job. Either hire an
editor, or arrange some kind of internal review team to clean up the
documents before you send them. If you don't give them trivial
details to distract them, it'll be much more likely that they'll
concentrate on the important things.

Second, send information to the right people, in small chunks. Two
aspects of human nature help you here: people pay more attention to
material that interests or concerns them than to material that isn't
relevant to them, and it's easier to convince oneself to focus for 10
or 20 pages (instead of ripping through a 100-page document and
paying little or no attention, just to get the paper off your desk).
So, ideally, send a 20-page chunk to the one guy in the company who
really cares about that section rather than a 100-page manual to
everyone, irrespective of their expertise. You do have to balance
quantity with frequency, though; nobody wants to be distracted 10
times a day to read a 1-page summary.

Third, educate your SMEs (perhaps include a specific checklist of
questions they must answer) and make sure they sign off on technical
details to accept responsibility for them. If they understand that
they cannot return a review copy without answering the question "Is
the timing sequence for the ADSL module correct?", and will be
held responsible (slap on the wrist? public execution?) if the
information is wrong, then they won't ignore the review. Implementing
this kind of system _will_ require some discussion with the SMEs so
they understand what's required of them and why, and _will
definitely_ require buy-in from their manager.

Finally, one of the most important lessons of all: Don't rely on
printed forms to accomplish something that should be done face to
face, via a conversation. Cover sheets are impersonal and easy to
ignore; 10 seconds of "don't worry about the grammar, just check the
following facts, and by the way, how's your Mom, Ed?" is far more
effective in getting them to do what you want.
--Geoff Hart @8^{)}
geoff-h -at- mtl -dot- feric -dot- ca

When an idea is wanting, a word can always be found to take its place.--Johann Wolfgang von Goethe

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=