TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
---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
testing.
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
needed.)
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
_________________________________________________________
DO YOU YAHOO!?
Get your free @yahoo.com address at http://mail.yahoo.com
