Reviewers

[jowen2 -at- CSC -dot- COM]

First of all... THANK you for the great response I got to my question!  I'm
meeting to do a release post mortem this week, and have pulled a lot of
your information (and my own observations) into a plan for our reviews.
Since I got so much response privately and on the list, I thought you all
might like to see what I've pulled together.  Feel free to use it if you
like (or shoot holes in it).  After discussing this with management and
technical leads this Wednesday, I'll be making a new review checklist based
on what we decide.

Again, thanks so much for your help!!!

Joy

*******
All,

Much of the time taken in document preparation happens during the review
cycle.  The following sections discuss some ways we can help each other
during the review process.

Reviewers

Avoid spending a lot of time on grammar and editorial reviewing.  If you
can look at the sentence and understand what it says - don't waste time
editing.  The tech writer will be editing the document for these things.
But if you find things that stand out (such as typos, incorrect spelling,
sentences that don't make sense) - please let the writer know.

Avoid editing things you've already edited.  Sometimes we'll find edits and
then in the very next review things are edited back to the way they were
before the last edit.  If it's something you aren't sure about - tag it for
the technical writer to have a look.

When returning review copies, please be very exact in what you want to say.
Partial input sometimes ends up in partially documenting your features.
Putting a question mark ends up with no features documented. :)

Avoid getting into discussions with people who are sharing your review
copy.  Many times, I'll end up with paragraphs asking so and so about such
and such feature and that person, in turn, providing info about such and
such feature to the originator - but this may or may not tell me how the
paragraph needs to be edited.  Be very explicit.  Try not to get into
discussions on the review copy.  Get your questions answered and then edit
the copy with the answers.

Avoid expounding on complex technical theories or processes.  Keep it
simple.  With as little time as we had, it took us so long just to decipher
what the reviewer was saying - and then to cut it down to only what was
necessary for the book.  If it helps to think in "noun/verb" only terms,
then when you are editing your doc, remember to write "This process does
this" or ... "This program now does this."

Writers

Meet with the project leader before the project.  Discuss how to assign
portions of the manual for review and how to set deadlines.

Turn change bars on to flag the changes that were made for this review.

Place questions or comments to the programmers in red text to flag the
programmers.

Prepare a standalone list of questions and attach it to the document being
reviewed.

If a manual is being reviewed chapter by chapter, include a TOC for the
document so that reviewers will know where a specific topic should be
covered in detail and where it should be mentioned in passing,
cross-referenced, etc.

Edit the doc as much as you can before it goes to review so that reviewers
aren't spending time correcting grammatical problems.

Provide reviewers with small chunks of data to review.

Consider reviewing documents orally with a reviewer rather than in writing.

Remind reviewers of review deadlines.

Questions for the Teams

Do we want only one review copy per team (shared) or separate review copies
for each team member?  Having only one copy means longer turnarounds for
review.  But also prevents duplicate or conflicting information from being
presented to the writer.

Do we want to have a review meeting at some point to sit down at a table
and hash out discrepancies?  Perhaps the final review?  Attendance at such
a meeting should be mandatory.  And reviewers must show up with the
document already reviewed and be prepared to discuss their changes.  No
reviewing should happen during these meetings!

Management Role

To quote from my Tech Writer email list:

Management buy in is probably the biggest asset you can have.  Managers who
encourage their staff to do conscientious reviews and allocate time in the
schedule and resources in the budget make it infinitely easier to get good
reviews.

Provide a reward system for some of the best reviewers.  Maybe get off work
early one day?  Something from the gift shop?

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=