Part 2: 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.

jfraser -at- glinx -dot- com
I've been through some of the problems you speak of as well. The one thing I
can suggest is that you provide a cover sheet with your review packages
designating each reviewer and they type of review they are expected to
perform. We stated also in the cover letter that while grammar and spelling
MAY be redlined by QA, Techies, etc., style issues/personal preferences must
NOT be marked up--this is the author's job and the Tech Writer Reviewer's
job.

We clearly defined the task of each reviewer and it seemed to work out quite
well. Plus, I found that it helped the reviewer relax and concentrate on her
area of expertise, not trying to perform every kind of edit. Reviewers were
happier and the review process went much faster.

e.g.,
Another Technical Writer - Grammar, Spelling, Consistency, etc.
QA - Company standards, client standards, policy, legal issues,
completeness,
etc. (some of what the tech writer does)
Techie (one or more of Engineer, developer, tester, etc.) - Technical
Accuracy. More than one is best, especially if the document is large and/or
each team member has their area of expertise (e.g., the portion of the
software they developed or tested).
Techies not on the project - They are often useful because often they pick
up
on things that don't make sense, they wonder why something was
written/programmed/etc. the way it was, and so on.

What can also help, is that grammar/spelling be marked on hardcopy, while
comments on technical issues, style, etc. be submitted via softcopy. Each
comment is designated as ERROR and COMMENT (or SUGGESTION) (anything else
you
may find useful). The item is identified by para/page/section. When all
comments come back (NOT grammar/spelling) collate them (there's often a lot
of
duplication among reviewers). This acts as a log (especially if you have QA
monitoring the review) to ensure all comments are addressed.

Example:
Error: (page 3, para 3)
The wingything is defined incorrectly. It should be defined as "blah, blah,
blah..."

Comment (Sec. 3-2, page 25, para 3-5)
I think it would be clearer if you defined this material in a table...

The person responding to the comments (updating the document) should
actually
enter a response as simple maybe as, e.g., "Done", "Not done because..." "no
time, deferred to a later version"... (whatever is appropriate). The log is
kept for reference for future versions, QA monitoring, etc.

Obviously, except for technical issues, it is up to the discretion of the
author whether or not a comment is addressed. (I've been through reviews
where
another writer "hacked my work to a slow painful death". Her writing style
was
different than mine, neither was wrong. But, that's why "at the author's
discretion" is important--if you're an experienced writer you know what
works.) The other point is this: Have only 1 (maybe 2) other writers on the
review team. There's no need for more. QA, Techies, etc. will provide the
feedback you need. Also, trying to wade through all the comments and
responding to each one will take you to a "slow painful death"! Again, save
yourself by clarifying the tasks up front!

Oh yeah, and, of course, don't forget to include editing checklists wherever
applicable (especially for style, consistency, formatting, etc.) for
reviewers
to ensure everything you want done gets done and you might want to collect
some metrics such as the time each reviewer spent on their portion of the
review, how much of the document they were able to get reviewed in the time
alloted, etc. This may help in preparing future reviews.

Okay, enough rambling. Hope this is some help. If you have any questions,
feel
free to email me.

PS: Re some earlier discussions on this topic: I have to disagree strongly
with the author who says sequester the team in a room for the review and
read
every word out loud. Ouch!
1. Who's got the time, I can see arguments going on for days, unless you got
one helluva moderator. Individual reviews are done way faster. And you end
up
with the same result if everything is logged by the individuals.
2. Who wants to write everything down by hand.
3. And what techie wants to listen to writers discuss style, standards, etc.
and vice versa!
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
mabels -at- csiks -dot- com
We use a single sheet: on one side, we have "Tips for Reviewing <company>
Documentation

We have a bulleted list of what to review for. This includes Structure &
Organization, Accuracy, Clarity, Spelling & Grammar, Consistency, Usability.
We can check any item or cross out any that don't apply to the intended
reviewer.

Second is another list of "What to say when you're not sure what to say:
o "I don't like this but I don't know how to fix it."
o "I don't like this and here's why..."
o "I don't like this. Write this instead."
o "I love this! You're a genius!"
Remember: Your candid observations won't hurt my feelings. But your
reticence
could hurt the documentation. Don't hold back.

Next is a Depth of Review sectio with check boxes for Read full document in
detail and Read marked changes/additions/deletions

Finally is a Review Priority that has check boxes for Review Immediately,
Review ASAP, and Review When You Can

Page 2 has the proofreader's marks. We've found that most people don't know
them (why would they?) but are glad to use them if we provide a copy.

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.