Part 4: Summary of Guidelines for Technical Reviewers

["CJACOBS.US.ORACLE.COM" <CJACOBS -at- US -dot- ORACLE -dot- COM>]

Thanks to everyone who responded to my request for suggestions on preparing
guidelines for technical reviewers. Here is a summary of the responses that
I
collected. I must send them as multiple e-mail messages, because this list
has
a 250 line maximum.

geoff-h -at- mtl -dot- feric -dot- ca
cjacobs -at- us -dot- oracle -dot- com, which is surely as odd a given name  as any I've
encountered, asked for suggestions on getting  good reviews from reviewers.
I'd suggest that rather than  producing yet another memo that nobody will
read, you work  on the other loose ends in the review process:

1. Get buy-in from the reviewers; get management to lean on  them if
necessary. Do this in person: talk to the  reviewers, develop a good
relationship with them so that  you don't just surface at review time, and
do
little favors  so they look upon your appearance with pleasure, not dread.

2. Give reviewers small, digestible chunks to review; it's  easy to do a
good
review of 5 pages, and damn near  impossible to review an entire manual
effectively.

3. Give them a quality product to review. If you clean up  all the grammar
and
style problems before they see the  material, they'll be able to concentrate
on the review, not  the writing. They will still play with your wording, but
at  least it will be a minor part of the review.

At the risk of oversimplifying, I've found two very  different types of
reviewer. Type 1 is excellent, thorough, and diligent, and doesn't need a
guide to doing reviews. Type 2 hates reading anything and won't do a good
job
no  matter what guidelines you provide... but will sit with you  and answer
questions for as long as it takes, but only if  you ask the questions rather
than providing them in  writing. (Fortunately, I've yet to meet Type 3, who
won't  do a review under any circumstances.) Type 2 will take more  time to
do
the reviews, and more coaxing, but the results  should still be fine.
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
rebecca -at- zlogic -dot- com
I'm working my way through a backlog of listserv mail and just came upon
your
message. I, too, am now working on creating a set of reviewers guidelines,
and
would love to hear what suggestions you get (and would be happy to send you
a
copy of what I'm working on, if you'd like to see it).
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Lshindley -at- angeion -dot- com
I assisted in developing a review process for manuals at my company. The
process greatly reduced the problems you stated. When we send out manuals
for
review, we place a cover sheet on the manual.

The sheet contains the title of the manual, revision if necessary, and part
number. It also contains a box for special instructions. We state the reason
for the review. In a bulleted list with check boxes, we have statements like
"read for clarity and technical accuracy," Technical accuracy includes
specs,
parameters, anything that may pertain to the manual. We also ask that they
make marks in the margins and use a red pen. There have been times, esp. for
larger manuals, when I provided those little 3M post-it tabs (1'' wide,
color
tab with clear tape to mark a page) so that I could find the comments
faster.

We also include the review list and space for sign-off. I am going to attach
a
shell template here, because I think my explanations might be confusing. I
will remove the logos and company reference. Hope this helps. It's jsut a
basic document, but I trust you will modify to fit your company's needs. If
you cannot open it. let me know. I can also send PDF if necessary.

(Send e-mail just to CJACOBS -at- US -dot- ORACLE -dot- COM if you want a copy of this
template.)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
kdrummon -at- worldnet -dot- att -dot- net
Go to page 312 in JoAnn T. Hackos book: "Managing Your Documentation
Projects."

Posts: mailto:techwr-l -at- listserv -dot- okstate -dot- edu
Commands: mailto:listserv -at- listserv -dot- okstate -dot- edu (e.g. SIGNOFF TECHWR-L)
Archives: http://listserv.okstate.edu/archives/techwr-l.html,
	http://www.documentation.com/, or http://www.dejanews.com/
Subjects: JOB:, QUESTION:, SUMMARY:, ANNOUNCE:, or none of these.