Early reviews

Subject: Early reviews
From: geoff-h -at- MTL -dot- FERIC -dot- CA
Date: Fri, 31 Jan 1997 09:53:51 -0600

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
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html

Previous by Author: Good web design
Next by Author: Procedural tables
Previous by Thread: Good web design
Next by Thread: Got the Info (was Joann Hackos Seminar)

What this post helpful? Share it with friends and colleagues:

Sponsored Ads