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

hilary -at- cygnuspr -dot- demon -dot- co -dot- uk
The following questions were used as part of a document review....

Documentation Review Questionnaire

Forward Planning
Targeting the Right Audience
Please give the job titles of those you know who would want to refer to the
document (not forgetting yourself!).
Identifying Key Tasks
For the above individuals can you gives examples of likely tasks for which
this tool will be used.
Tough Issues/Hints/Tips?
Please identify particular areas where you feel particularly detailed
accessible documentation would be useful.
Paper or Screen?
Please indicate your preference between conventional paper documentation and

on-line hypertext type documents, together with any relevant reasons or
notes.


Current Material
Factual Errors
Please note any factual errors you have encountered in the guides.
Discrepancies/Inconsistencies
Please note any discrepancies or inconsistencies you have found.

Missing Information
Please note any areas where you are aware that information is missing or
incomplete.

Structure
Please comment on the structure of the documents. Did you find it logical?
Were you able to find the information you required?

Style
Please comment on the style of the document. Was the content easy to
understand? Did it make sense?

Terminology
Did you feel that specialist terminology was adequately explained? Was it
used with consistency?
Indexing
Did you find the index useful/adequate?


General Comments
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
thomerson -at- bgs -dot- com
Hi,

Your goals are good ones, but in my experience, few reviewers read the
guidelines, even if they're bolded on the review memo. In fact, right now,
I'm
struggling with a reviewer who "*has* to copyedit every document", even
though
she's been asked and told repeatedly NOT to (she's in our QA department).

The best results I've had from tech reviewer guidelines was to prepare a
document, call a doc kickoff meeting, stand in front of the group (we had a
good turnout because we had food) and go over them. I paid special attention
to the nonverbal responses, and would stop occasionally to ask if anyone had
questions, or if I should clarify certain points. We slanted the
presentation
to accommodate engineers (although we had marketing, QA & tech support
there,
too), and made sure we made the point that we knew time for reviewing was in
short supply. We gave people tips for maximizing the time they spent (e.g.,
if
you get a chapter to review, you could split it up with a couple of people,
with each person reviewing the sections that they knew best, and also, when
you get a chapter that's been through at least one review, look just at
change
bars to review only info that's been changed). Finally, we pointed out that
documentation is everyone's responsibility, although few schedules include
enough time for it, and to ease the stress, we gave out "stress reducers"
which were just little dime-store toys such as clackers, play-doh,
paddle-ball
thingies.

We had really positive feedback from it, and the effectiveness of subsequent
reviews was better than before. Hope these ideas help!
Feel free to write back if you want more info!
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
jstanley -at- roadshow -dot- com
I've recently become the lone tech writer at a company that hasn't has a
documentation person in its 10 years in business. I'm getting close to
submitting my first doc for technical review by the programmers. (It will
also
go to other reviewers, including product managers and so on, but that's
primarily for "political" reasons--the programmers will be considered the
line
of defense for technical accuracy.)

Because they haven't before had any formal process for tech reviews, I'm
trying to get across the idea that I need their technical input, but not
their
editorial input....and I'm trying to get it across *gently*. I'm also going
to
ask them to sign off on the docs they've reviewed. Again, this isn't
something
they've had to do before, and I can foresee it causing resentment, so I'm
trying to put the idea across in as non-threatening a way as possible, by
suggesting that it's really for the sake of keeping me organized.

The attached document is a sort-of "heads up" for the programmers, to say
here's what's coming up and here's what I'm looking for from you. (So far
only
one programmer has looked at it, and she hasn't expressed any objections.
I've
been trying to get the head of development to read and comment, but haven't
had any luck. But that's another story. ;-0 )

I don't know whether this will be of any use to you or not, but here goes.
This is a Word 97 doc; if you can't get it as an attachment, let me know and
I'd be happy to send it as text pasted into an e-mail message.

An aside--You talk about asking your reviewers to work through procedures
step-by-step and to compare screen shots on the page to actual program
screens. I wonder...are those tasks that have historically been the
responsibility of the reviewers at your company? In the places I've worked,
they were considered the responsibility of the documentation department.
Now,
the doc department might perform those tasks by doing its own technical QA
(not the same as editorial QA), or it might farm them out to a freelancer or
"borrow" help from another department, but the docs people were definitely
*responsible*. I'm always curious to hear how it's done in other places!

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.