Re: Format for receiving document reviews

[Hsuan-min Chou <hchou -at- OPENPORT -dot- COM>]

In the 3 companies I've worked/contracted for, I have never used an online
reviewing process. This is, in large part, due to the fact that most people
I know don'twant to review a hundred-plug page manual on their PCs (if
their PCs can even handle it). Most of my reviewers read doc on the
commuter train, or late at night. Also, trying to read a manual online w/
the application on the screen at the same time is tough.

Furthermore, online review tools, while helpful and speedy once you're past
the learning curve, are often a hindrance. Generally, I print out the
manual and/or help file, and send a copy of it to everyone directly
involved w/ the project (managers, developers, analysts, other doc
writers). My manuals usually havea large margin for commetns.

I attach a cover page indicating

* what I want them to focus on (organization; clarity; accuracy; grammar; etc)
* what not to pay attention to (picture placeholders; style)
* the due date
* a place for them to sign their name indicating they did, in fact, review
it (this is known as CYA -- Cover Your Ass). If there is any misinformation
in the manual, then that reviewer will be held partially accountable. If
they don't send a copy back (after several reminders from me), I have to
assume that they didn't have any problems with the manual. I just don't
have the time trying to chase people around, and who probably have a dim
view about documentation in general.

For online help, RoboHelp Office has a tool taht allows you to decompile
the .HLP file into a single Word document. I compile the help, and then
decompile it for a number of reasons:

* if I simply print out the help source (.DOC) files, I will ALWAYS get
useless comments from reviewers asking about: those "strange" footnotes;
absence of bitmaps/graphics; those weird "{bmc graphic.bmp}" references;
etc. Even if you tell them not to pay attention, to them it's distracting.

* all those page breaks in the source .DOC file make the online draft
bigger than it needs ot be (and wastes paper)

* the decompiled HLP looks cleaner (see above), and include graphics, etc

* it's easier to print one .DOC file than a number of source .DOC files

* all the topics are printed, including popups and glossary terms

* if you use the annotation feature in hte .HLP files, you have to explain
to people to send you the annotation files (i think it's *.ANN). Generally
-- unless your reviewers are very computer-savvy -- it's more trouble than
it's worth.

* using the .HLP, they probably won't see EVERY topic, e.g., popups, etc.


At 02:39 PM 6/19/98 -0400, you wrote:
>I was wondering if anyone out there in technical-writing-land has the
>magic answer to what is the best way to receive comments from
>developers/engineers on the documents you write.
>
>Specific questions I would like answered are:
>*       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?
>*       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?
>*       Do any of you use the method of printing out documents and
>asking the reviewer to write their comments directly on the paper?
>*       How have you dealt with the "unresponsive" reviewer?
>*       How do you ensure that you do receive comments back from the
>reviewer in a timely manner?
>*       Do you have any examples good and bad experiences with reviews
>of your documentation? Please share!
>
>Thank you for any information and help you can give me.

**************************
 Hsuan-min Chou
 Open Port Technologies
 Marketing

 (e) hchou -at- openport -dot- com
 (t) someday
**************************