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

timmerma -at- ipdlink -dot- ipd -dot- anl -dot- gov
You have an excellent list. I also think you should include a reference for
checking the document for completeness, (i.e., Is anything missing from the
document.).

I get the impression that you are writing software manuals. When I wrote
non-commercial software manuals, I performed the software reality check
against the docs. That task is very time consuming and I doubt that the
reviewers will do it, and if they do, it probably won't be as good as the
check you perform.
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
mspurgin -at- is -dot- com
I'll be very interested in the responses to your posting.

At my company, the technical writers primarily write system requirements.
Developers often complain that the requirements are too thin, even though
they
HAVE reviewed the document. I would add to your list:

Think through how you would build the system with the information provided.
Do
you need more information? If so, what kind?
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
john_glenn -at- geocities -dot- com
My SOP in the past has been to attach a cover letter to the doc to be
reviewed
-- this also could be an email, but I prefer reviews on paper -- stating
what
I expect from the reviewer and that failure to return the reviewed document
will be considered a /review without comments./

This is about the ONLY way I know to get responses ... hold the reviewer
responsible, but be fair in the amount of time for the review (take into
account in-progress activities, illness, vacation, etc.). As a general rule,
if the reviewer
(a) knows you depend on the review
(b) seriously consider review comments (if you disagree, tell the reviewer
why
... perhaps you BOTH are missing something)
(c) has a vested (or even polo shirt) interest in the document (i.e. a PE
can
lose a license if an admonishment is omitted and someone is injured/killed
or
a critical [read money-making] operation] is halted )
AFTER the reviews are in and the changes (never /corrections/) are made,
make
it a point to personally thank each reviewer ... if you can manage it, take
them to lunch -- make a fuss. You're gon'na need these people again. Makes
you
part of the team; makes them part of the team.
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
hayenl -at- inel -dot- gov
We have a few things that might help.

We request that the SMEs use a discipline-specific checklist (or equivalent)
during the review. (In other words, QA reviews for quality; S&H reviews for
safety and health; the tech editor reviews for format, etc.) We also tell
them
that while we appreciate any comments, we'll only consider significant
review
comments from a person's area of expertise. (Sig. review comments are those
-within the person's area of expertise- where not implementing them will
violate a standard, order, law, reg, higher-level procedure, etc.)

We have a disclaimer that goes out w/ the review package: Comments received
after ____ will be held for the next review. The only way this works is if
you
have management backing and the policy in place.

In the past, we've offered classes on reviewing documents. (All it is is a
basic how-to-edit class).
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
kitw -at- supercede -dot- com
I saw your posting in techwr-l about getting good technical reviews returned
on time.

Just thought I'd suggest you add/ emphasize that reviewers please provide
useful information. As in, "don't just cross out the procedure, or say
"that's
wrong!" Please tell me how to make it right, or point me toward finding the
right answers."

Might be obvious, but I've had the experience of whole pages being scratched
out and annotated "Bulls***!" which obviously is not very helpful. (In that
case, I returned to the reviewer and said "OK, so you say it's Bulls***.
What's the right answer?!"
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
kjolberg -at- ix -dot- netcom -dot- com
One technique I've seen employed a number of times is to require a signature
from a reviewer. My personal experience as a technical reviewer is that it's
a
lot harder for me to put my signature on something when I know darn well I
haven't looked it with a critical set of eyes.
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
JHUXTABLE -at- datastreamicv -dot- com
I saw your request for information on the TECHWR-L list.
It seems a constant problem to get reviewers to do the specific job you want
them to do - if only all the SMEs were ex-Tech Writers! 8-)

One publication I have found here in the UK is worth a look. It's written by
the top recruitment/consultancy agency for Writers in the UK. It's a PDF
file,
find it at:

     http://www.kudos.co.uk/pn-pubs.html

The title is "The Kudos Guide to Information Reviewing".

(I do not have any connection with Kudos except as a satisfied customer.)

I shall look forward to seeing your collected responses.
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
droberts -at- panix -dot- com
In article <199711111318 -dot- FAA22621 -at- mailsun2 -dot- us -dot- oracle -dot- com> you wrote:
: The sorts of tips that we'd like to include in our document are:

Some other things you might do is:
* inform reviewers of changes in the document structure or format. reviewers
can sometimes get upset if things dont look the way they used to.
* indicate if only specific sections are updated, and require review. Why
review all the material, if only certain sections changes. But then again,
they could spot pre-existing errors in unchanged parts.
* if you're sending only a portion of a doc, explain how the portion fits
into
the rest of the doc. The reviewers might know the structure and content of
the
entire doc.
* perhaps explain the audience for the doc. Information for low level end
users is different than for advanced program developers. Otherwise,
reviewers
might try to cram all sorts of technical details in a doc intended for the
first time user.

a couple more thoughts:
* perhaps indicate your stage in the review cycle - is this a first draft,
filled with errors, or the last draft, corrected and ready to the published.
* indicate the level of comments you can incorporate. For example, you can
take even the most minute changes in a first draft, but the last draft
should
have only 'showstoppers' corrected and all other changes (depending on your
time and resoure) tabled for release notes or the next release.

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.