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.
Subject:Re: Format for receiving document reviews From:Mark Forseth <markf -at- MERGE -dot- COM> Date:Mon, 22 Jun 1998 13:55:07 -0500
>* Is there a good method for an online review. For example, for
>help files, we don't want anyone mucking around with our .RTF files -
>what are other options for adding comments to help panels?
Most of the universe shuns electronic review (preferring hardcopy), but if
you're determined to go electronic, your best bet is Adobe Acrobat, which
allows each reviewer to write "post-it" comments on the electronic
document. The acrobat PDF file cannot be edited easily, so reviewers can't
mess with the text and such. Acrobat also collates electronic "post-it"
comments from multiple copies of identical files.
>* How about an online review of FrameMaker documents - is there a
>tool that we can use to put "post-it" type notes on the document pages
>but that are easy to delete from the document afterwards?
FrameViewer for FrameMaker may have a feature like this. Check
www.adobe.com for FrameViewer details.
>* Do any of you use the method of printing out documents and
>asking the reviewer to write their comments directly on the paper?
Hardcopy markups are the industry standard and preferred method, and
provide a nice paper trail of review progression (or lack thereof).
>* How have you dealt with the "unresponsive" reviewer?
Make it clear that management expects all reviewers to respond. Failing
that, direct the faulty reviewer's superior to the defect.
>* How do you ensure that you do receive comments back from the
>reviewer in a timely manner?
Schedule a group review of a manual after everyone has a chance to read and
comment on the manual. Anyone who doesn't show for the group review is
conspicuous in their absence.
>* Do you have any examples good and bad experiences with reviews
>of your documentation? Please share!
In general, hardcopy reviews are of three types (Serial, Collated, and HII
or Group) listed here from worst to best (IMHO), with some pros and cons:
SERIAL REVIEW
One copy of a manual is circulated to all names (SMEs) listed on the
reviewer sign-off sheet accompanying the manual. The review must be
completed within a specified time. Reviewers initial each comment they make
in the manual.
Pros:
Less-paper office (LPO); requires only one copy of a manual for review.
Eliminates the need to collate multiple reviewers' markups, from multiple
copies, onto one master markup. Successive reviewers see previous
reviewers' comments.
Cons:
One lax reviewer can hold up the entire process, or worse, lose the copy
with others' labors written all over it. Reduces review time for each
reviewer (compared to other methods). Early reviewers don't see later
reviewers' comments. Other's comments may adversely influence successive
reviewer input. Reviewer input and attention to detail wanes as the manual
moves throught the serial progression.
COLLATED REVIEW
Each reviewer gets a copy of a manual to mark up within a specified time. A
reviewer sign-off sheet accompanies each reviewer's copy. Reviewers
relinquish their review copies to the tech writer at the end of the review
period. The tech writer collates the markups into one master copy to be
used for generating the next draft. Collating markups reveals conflicts
(which the tech writer resolves) among reviewers.
Pros:
Each reviewer has more time to review than serial review allows. Reviewer
attention to detail is not affected by others' written comments as may
occur in serial review. Each reviewers' comments are recorded on their
review copies. If a reviewer loses their copy, it doesn't compromise the
whole review.
Cons:
Paper consumption is greater than with serial review. All reviews must be
collated into one final markup if only to reveal conflicting comments --
then the conflicts must be resolved before generating the next draft.
HIGH-IMPACT INSPECTION (HII) or GROUP REVIEW
Same as collated review, but all reviewers meet at a specified time/place
to discuss their comments and markups, page by page. The tech writer
mediates the meeting, collating all comments onto one master markup.
Reviewers relinquish their review copies to the tech writer at the end of
the meeting.
Pros:
Same as collated-review advantages. Also: Reduces the number of reviews
required for new-product documentation. Group meeting after initial,
individual review encourages each reviewer to actually review the manual.
Anyone who has not completed their review is not allowed to attend the
group-review meeting (these people stand out before long). Conflicting
comments, opinions, and markuyps are resolved instantly. Everyone knows
what each other commented. Helps SMEs resolve product-related issues.
Reveals weaknesses in processes, product design, team communications, etc.
Among product-design team members, clarifies product-related
misunderstandings that may otherwise have gone unnoticed without group
discussion. Too many advantages to list here.
Cons:
Paper consumption is greater than with serial review. People not accustomed
to this review process may resist the process change. Difficult to get all
reviewers to meet at the same time, and for two or four hours.
