Technical review of documentation?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Indira Upadhayaya wonders: <<Have you ever educated developers "how to"
review documentation ? For example, what are the necessary checks to ensure
technical accuracy of the documentation?>>

Training developers to do good reviews is like training cats to walk on a
leash: you can do it with some of them, but it's going to take lots of
patience and you won't succeed with everyone. The only really reliable way
to get good reviews is to develop a sufficiently good working relationship
with each potential reviewer that you know how they prefer to do reviews and
can persuade them to try: some want printouts, others want to review in
Word, and others want you to hold their hand and read the documentation to
them while they sip milk, nibble on cookies, and gaze at the ceiling.
Really.

Whichever format you use, edit it rigorously so that there are no
grammatical or typographical problems for them to correct; this way, they're
far less likely to be distracted by anything other than technical errors.
Asking them to review docs in a manner that they're not comfortable with is
a recipe for failure, but even once you know how they prefer to receive the
reviews, you still need to do two more things: first, explain the process
and your needs to them in person (or over the phone) so they can ask
questions and you can make sure they understand what you want; second, send
them a printed or e-mailed summary of your discussion, since they might
forget what you discussed. Ideally, have at least two reviewers check each
document, since what one misses, the other might catch. Last but not least,
_their_ managers must give them a strong incentive to do good reviews:
rewards for doing the job right and catching lots of errors, penalties for
missing errors, or a combination of the two.

<<Are there any worthwhile checklist available?>>

Yup: it's called the documentation. <g> Every word and every sentence must
be correct, and it's the reviewer's job to be sure this is the
case--reviewers are the only ones who can do this, since you're not the
expert. In addition, a good reviewer will also point out anything that's
missing, including exceptions to what you've written, alternatives that they
recommend to some of the procedures you've written, and statements that are
technically correct but perhaps misleading or incomplete.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"Computers are like Old Testament gods-lots of rules and no mercy."--Joseph
Campbell

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Be a published author!  iUniverse gives you: a high-quality paperback, a
custom cover design, and distribution to 25,00 retailers.  Join our almost
10,000 published authors today. http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.