Re: Electronic Review

[Gary Merrill <sasghm -at- UNX -dot- SAS -dot- COM>]

In article <30C5D7BF -at- admin -dot- eicon -dot- com>, Lazarus Slater <lazaruss -at- EICON -dot- COM>
writes:
|> We are looking for some feedback on electronic review of documentation.
|> We are presently in a Windows and OS/2 environment and would like to know
|> if anyone has any experience or comments with electronic reviewing of
|> documents. We have been exposed to both Adobe Exchange and Frame Viewer.
|> Any feedback on these or any other products would be greatly appreciated.

Several years ago when I was managing a group developing our C++ compiler
we made the decision to do the documentation in FrameMaker and to use
electronic review.  After this project was complete, the technical writer
and I each wrote a summary and analysis of the documentation and review
process.  We had thought about publishing this, but never got around
to it.

There was not much in the way of support for online review in FrameMaker,
and I wrote a package to do this:  BORED (Basic Online Review Environment
for  Documentation).  This software allowed each reviewer to create
and maintain his own review file that contained comments.  For each
comment, the reviewer was to indicate (by a rather simple syntax) the
chapter and range of lines the comment applied to.  General comments
were permitted as well.  A utility was provided to collate all the
comments in the current versions of all review files and produce a
single file of comments arranged in order of chapter and page range,
and with the reviewer identified for each comment.  This allowed
reviewers to see the comments of others and provided an organized
presentation of the full set of comments for the technical writer
to work from.  FrameViewer was used to view the document.  The
reviewer files were simply text files created via the reviewer's favorite
editor.  The interface to BORED was a simple command line interface.
If I had it to do over, and had the time, I'm sure I could provide
a slick interface in X-Windows and perhaps even embed it more
closely within FrameMaker/FrameViewer itself.

In general, reviewers felt that the online review process offered
some significant advantages.  Paper copies didn't have to be
shuffled back and forth, there was no delay in producing multiple
copies on paper, reviewers had immediate access to the latest
version of their colleagues' comments (and on the basis of this,
discussions could take place -- often in email -- to raise
issues and resolve points of confusion or dispute).  We
felt that online review streamlined the review process
and contributed to a greater degree of interchange among
the reviewers and writer.

Some reviewers felt that having a paper copy of the document
in addition to the electronic one was essential.  I ascribe
this partly to the fact that old habits die hard and partly
to the very limited capabilities of BORED.  Better software
for electronic review would support the attachment of comments
directly to the document itself and allow for various ways
of viewing and managing these comments.  I do not know what
capabilities current versions of publishing software support.
At the time I was surprised that no one seemed to have taken the
need for and value of such online review seriously enough
to add support for it to their products.






--
Gary H. Merrill  [Principal Systems Developer, Compiler and Tools Division]
SAS Institute Inc. / SAS Campus Dr. / Cary, NC  27513 / (919) 677-8000
sasghm -at- theseus -dot- unx -dot- sas -dot- com ... !mcnc!sas!sasghm