Re: Online Document Reviews

Subject: Re: Online Document Reviews
From: Richard Lippincott <rlippincott -at- YAHOO -dot- COM>
Date: Tue, 12 May 1998 07:59:16 -0700

---Gail Gurman <gail -at- HOMEMAIL -dot- COM> wrote:
> Our Tech Pubs department has been told to migrate away from paper
> document reviews to online reviews. In other words, documents would
> be provided online in HTML and reviewers would have to, somehow,
> provide comments without using paper.
> Personally, I am having difficulty imagining how this will work. Do
> any of you out there do online reviews? How do you handle them?

Gail, I've got to second what Eric Ray said: the quality of the
comments depends on the motivation of the reviewer.

I'm in an unusual position regarding this: I'm the company doc
reviewer, and I've been doing it all online. Yeah, there are times
when it seems like it would be simpler to just redline some paper, but
I know that the online process is making things easier all around.

Here's a quick rundown of how it works at our company:

1) When a new project is underway, tech pubs and the developers work
to prepare the software and the docs.
When they're ready, each releases their part to the QA group for

2) I'm in the QA group. I take the new and changed documentation.
During the functional tests, I run through all the new/changed
material, using the QA testing systems. I also look for material that
-should- have been changed, but has been overlooked.

3) If I have comments, I generate bugs in our defect tracking system.
The bugs automatically are sent back to the tech pubs management.

4) Most times, the description of how to make the change is simple
enough that I can put it in the bug description ("Step 4, tell the
user to log into the maintenance mode first..."). If the changes
involved are more complex, sometimes I find it easier to make a copy
of the writer's Interleaf source file, re-write it as needed, and then
e-mail it to the tech pubs department.

5) If the tech pubs agrees with my changes, then the changes are
incorporated into a new doc set build. If tech pubs disagrees, we
discuss it. (And sometimes I'm wrong, so I change the defect report as

We've been doing it this way for nearly a year now, and it seems to be
working quite well. What's also helped is that I'm becoming more
visible as the contact point for problems with the docs. If people in
QA, training, or tech support have a problem with the docs, they tend
to call me. I check out the procedure, and if necessary generate
another bug.

But as Eric said, it's a matter of motivation. I'm in this job because
I convinced management that the position was needed. Thus, my
motivation is high. Technically, we could have been doing this same
thing two years or five years ago, but nobody here was motivated
enough to sit down and do a line by line analysis of the docs.

But it is working well. It -can- work well, but motivation is the key.


Richard Lippincott
Comverse Network Systems
Andover, Massachusetts
rlippincott -at- yahoo -dot- com
rjl -at- comverse -dot- com

Get your free address at

Previous by Author: Re: Non-technical, Technical Writers
Next by Author: Re[2]: New slant: professionalism
Previous by Thread: Re: Online Document Reviews
Next by Thread: Re: Online Document Reviews

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

Sponsored Ads