Documentation Review?

[Geoff Hart]

Annie Wood wondered: <<We are currently reviewing our documentation  
processes and are looking to get some feedback about how other teams/ 
companies handle reviewing their documentation.>>

There's a bunch of useful stuff on my Web site: http://www.geoff- 
hart.com/resources/bibliography.html

<<Do you have a process for reviewing/testing/proofreading  
documentation?>>

We've had one everywhere I worked. Lessons learned are discussed in  
the various references on my site.

<<What do you review in the documentation? Content, grammar, layout,  
style (both wording and/or applying templates), or functionality of  
the Help (other documentation)?>>

All of the above, plus other useful things like clarity, accuracy,  
and completeness.

<<Who reviews the documentation? Another technical writer, editor,  
proofreader, SME?>>

Anyone with a stake in the outcomes or the ability to improve the  
quality of the final product. For more details: http://www.geoff- 
hart.com/resources/2005/reviews.htm

<<Do you use any sort of defecting tracking software?>>

Not generally. We did keep old file copies showing what changes were  
necessary as a result of review, but the goal was more to help people  
learn the kinds of things they were missing than to punish anyone.  
With software, the developers did indeed keep track of bugs and other  
problems in a database of some sort.

<<Do you provide the reviewer with anything explaining the changes in  
the documentation?>>

This kind of discussion is an important part of any review process,  
since it builds a sense of teamwork and cooperation--at least if done  
right. <g>

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --

Geoff Hart   ghart at videotron.ca

(try geoffhart at mac.com if you don't get a reply)

www.geoff-hart.com

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -