Re: Annotating Review Comments

Subject: Re: Annotating Review Comments
From: Matthew Stern <MAStern -at- PLATSOFT -dot- COM>
Date: Mon, 14 Oct 1996 12:53:00 -0700

I'm responding to the messages about distributing source files for
review and having reviewers annotate the files. (The latest one is from
Robert Plamondon.) My issue might be a tangential one, but it's one
worth considering.

I have had little success with electronic reviews. This is not because
of the technical aspects. It is because most reviewers I've come across
won't read the documents on line.

At a previous job, we tried to make online reviews *mandatory* in an
effort to reduce duplication costs. We also hoped that online reviewers
might encourage the less forthcoming reviewers to return comments.

Here is what actually happened: The people who weren't good about
returning review comments on hardcopy documents were just as laxed about
returning comments online. Not only that, we got even less response
sending out online reviews than we did on hardcopy. The reason was that
we sent the reviews by e-mail. Engineers who keep dozens of e-mails in
their inbox were likely to overlook it. They were more responsive when
they had that stack of paper on their desk.

And speaking of paper, we found that most reviewers printed out the
online document and marked it up by hand. So, that didn't solve our
problem of reducing duplication costs. (It made printing costs worse
because we could duplicate the document double-sided, while the
reviewers printed it out single-sided.)

Here is what we wound up doing, and it seemed to work better:

* We asked reviewers whether they preferred review comments on paper or
online. We gave them the document in the format they preferred. (Most
wanted it on paper, though.)

* We followed up with the reviewers in advance of the deadline to track
their progress and encourage them to move along, if they haven't

* We worked with department heads to ensure that documentation review
was made a priority and part of employee's performance reviews. (We
didn't name names, of course. We just worked on producing an environment
where documentation reviews were considered important.)

Hope this information helps.

Matthew Stern
Sr. Technical Writer
Platinum Software Corporation
mastern -at- platsoft -dot- com

<robert -at- PLAMONDON -dot- COM>

For god's sake, whatever you do, don't let the reviewers touch your
actual source files. You'll never undo the damage they cause.

As for annotations in general, Interleaf has a very nice system for
this sort of thing, with what amounts to post-it notes that are stuck
onto the margins of the electronic review copy. Each reviewer can
be assigned a different shade of post-it note, which will be used
automatically for all their comments. They can make both public
(visible to the other reviewers) and private ones (visible only to the
author). This allows people to comment on comments, which can be very

I suspect that this might be an ideal way to maintain many kinds of
documents, where you would like the alleged facts to be accessible
they are checked out, phrased properly, cross-referenced, indexed, and
published to the world.

I must admit, though, that I've only read the manual on this feature --
I haven't had a project in which to try it out.

-- Robert
Robert Plamondon, President/Managing Editor, High-Tech Technical
Writing, Inc.
36475 Norton Creek Road * Blodgett * Oregon * 97326
robert -at- plamondon -dot- com * (541) 453-5841 * Fax: (541) 453-4139


Previous by Author: Technical Writer opening -- Irvine, California
Next by Author: Re: acceptable error rates
Previous by Thread: Re: Annotating Review Comments
Next by Thread: List of mailing lists for technical communicators

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

Sponsored Ads

Sponsored Ads