long RE: Online Document Reviews

Subject: long RE: Online Document Reviews
From: Alexia Prendergast <alexiap -at- SEAGATESOFTWARE -dot- COM>
Date: Tue, 12 May 1998 12:36:42 -0400

In my experience, "silently amended docs" are not *reviewed* docs. I
agree -- simply making the corrections instead of having the writer do
it does not benefit anyone in the long run.

Our online review process looks very much like our hardcopy review
process did, except that we get more thorough review comments from our
developers now.

Here's what we do:
1. Writers send out PDFs. (You can get a subset of Acrobat Exchange for
a nominal price these days. I understand there are other tools out
there, too -- the actual tool/format doesn't really matter, IMHO.)
2. Reviewers make their comments on the relevant pages on the PDF, just
as if they were marking up a hardcopy. I have one or two
upper-management/VP types who just don't do online reviews. They get
hardcopy. (We've found that reviewers are much more likely to do the
review on time and they are also much more likely to fire up the
application and actually check things as they review online. As always,
you have some reviewers who are more effective than others -- in our
experience, however, the ratio of effective reviewers increases with
online reviews.)
3. Editors do a hardcopy (and sometimes online) pass. Hardcopy's been
their preference. (When I'm doing a tech review or a peer review, I
prefer online. When I'm editing, I prefer doing a pass in each medium --
I'll catch different things by looking at it in different ways.)
4. The writers import all the comments into one file, evaluate the
comments, discuss the ones with which they disagree, and address the
others by making the corrections.

Not too different than traditional methods, eh?

We use a version control system, so we can go back to older
pre-review/correction versions, if necessary. Also, if you use
FrameMaker, you can use the Compare feature to make sure all changes
were made. If you use Word, you can use the Comment or Revision features
to comment or track changes. And so on. There are lots of ways to do
effective online reviews.

DISCLAIMER -- If you have a technical, geeky reviewer audience, online
reviews might work for you. If you have a reviewer audience for which
computers and online stuff is not second nature, you might have a more
difficult time getting them used to this. Use common sense.

There are other factors in getting successful reviews, of course, such
-Attitude ("Here you go, you wicked, uncooperative, spawn of Satan"
probably won't win you any points. Try developing a partnership based on
mutual professional respect.)
-Direction ("Here's another 1000pp review... get back to me whenever you
get around to it..." probably won't be very effective. Try a smaller
chunk due by a particular date.)
-Instruction ("We're doing online reviews now... we use <product>... you
can guess the rest" isn't too helpful. Nor is writing 100pp of
convoluted instructions. With each review, include concise instructions.
The first time or two someone local is going to review something online,
stop by and show them how.)

Any other tips for effective online reviews?


Alexia Prendergast
Tech Pubs Manager, Seagate Software
Durham NC USA
mailto:alexiap -at- seagatesoftware -dot- com

> -----Original Message-----
> I like paper reviews for one additional reason: the writers can learn
> from
> them. Silently amended docs don't teach the writers their weak spots
> and
> habitual errors; if they see their errors, they can improve their
> writing
> (and future edits can then concentrate on deeper matters).
> ...pat.

Previous by Author: JOB: tech writer: RTP: NC: Seagate Software: cross posted to tech wr-l and framers
Next by Author: long: Coincidence? I think not. Release Notes and READMEs
Previous by Thread: Re: An editor's duties (was: Online Document Reviews)
Next by Thread: Re: Interview Questions (a question)

What this post helpful? Share it with friends and colleagues:

Sponsored Ads