Early reviews

[geoff-h -at- MTL -dot- FERIC -dot- CA]

 Sue Heim wondered whether it was too early to do an
 editorial review of her online help simultaneously with a
 technical review for a product that is still evolving
 rapidly, under tight deadlines.

 Actually, Sue, my gut reaction is that it's far too early
 for either kind of review. If, as you note, the product
 really has no design specs (so some things don't work as
 they're intended), setting some specs is far more sensible
 at this stage than doing any kind of review. How can the
 developers review something if they have no standard
 against which to review it?

 Typical scenario: [Engineer to Sue] "The menu function
 'eliminate tech. writer' isn't documented at all, and we
 feel this is a particularly important part of the
 software's functionality. And for some reason, you think
 that the function 'help' is intended to help the user;
 actually, it's intended to help _us_ relieve our stress.
 When you select it, the software launches a customized
 version of Doom with all the monsters resembling the
 Project Manager."

 Yes, that's facetious, but you can probably fill in real
 details from your own context. If you can spend a day
 establishing something that resembles a functional spec,
 and set up a process that will notify you whenever the spec
 changes, you'll make your life immensely easier. Only then
 should you worry about reviews.

 Other points: If you really must do reviews at this point,
 send the reviewers _tiny_ chunks that relate specifically
 to their area of expertise. You'll get a much better review
 than if you expect them to review the entire system. Beware
 the pitfall of the overly frequent review: after someone
 looks at it for the third time, they're likely to miss
 mistakes so big they need their own documentation. Lastly,
 the notion of engineers doing editorial review strikes me
 as questionable... I have no kick against engineers, but
 isn't this like asking your editor to do code and algorithm
 reviews? Everyone's an expert at something... the trick is
 knowing what, and getting the right person to do the job.

 --Geoff Hart     @8^{)}     geoff-h -at- mtl -dot- feric -dot- ca
 Disclaimer: Speaking for myself, not FERIC.

 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