Electronic Review of Documents

["Dimock, Dick" <red -at- ELSEGUNDOCA -dot- ATTGIS -dot- COM>]

Lazaruss asks for feedback:

We are looking for some feedback on electronic review of
documentation.....

We use it at ATT GIS for our software development and
documentation.  It is an excellent tool for us.

We use a mainframe-based system that has evolved over
many years and is now accessible from several development
platforms.  I hope you get feedback from others on Windows-
based software.

Development began the system to track changes to software,
and to make sure the change moved properly along the
channels.  It became a tool for reviewing development specs,
and then we climbed onto the system.  We call it, appropriately,
the "DOC system."

When we have a manual to review, we place the files (Frame)
in a directory available to all, read-only.  We also open a
"Design Note" on the DOC system announcing the review files and
review schedule.  Reviewers type their comments into the Design
Note.  The writer reads the Design Note comments and makes the
changes to the manual for the next edition.  After making the
changes, the writer types a brief acknowledgment into the Design
Note, showing the comment has been considered, entered, or
refused (and why).

The Design Note and the electronic review files play a large part
in the documentation process, and directly parallel the
Development change control process.

It does get tedious, when I have 10 pages of printout of 2-line
comments, to acknowledge each with "Yup, you're right," or
"Will appear in a later edition," etc.

But there are several advantages:

BIG advantage:  Programmers are at home with their keyboards.
They will type happily and verbosely.  We get really good
feedback this way, compared to the old  " ?? " kind of comment.

Medium advantage:  The comments are in one place, not in
several marked-up copies

Advantage:  All reviewers have access to all comments, and
can cross-argue about technicalities right there in the Design
Note.  The writer can refer one SME to another SME's comment
and get a fruitful debate going between the SMEs.

Advantage:  I can floppyize the Design Note for easy carry,
compared to the dozen markup hardcopies.

I am sure the Lotus products and the Microsoft products can do
all these functions.  I hope others will comment.

One more point.  The culture here was already infatuated with
the DOC system for development use.  We were added to a
working system.  To do this from the ground up might require
building the culture to accept and use such a system.

And we still pass out hardcopies to all reviewers, for their
convenience, so they can read hardcopy if they wish.  A few
reviewers still prefer red ink on paper, and this is still an
alternate method.  Never turn down a comment!  We have
rules about retaining hardcopy review comments for a long time
for ISO purposes.  The electronic Design Note is easier to
store and satisfies ISO requirements.

I have no experience with electronic reviews in smaller groups.

Good Luck!

Dick Dimock    Now on page 2 of 10 pages of comments
          at

ATT GIS        which undoubtedly has more comments,
          a never-ending stream of comments,
          travelling at Network Speed to my tube,
          a veritable plethora of comments imploding
          upon me, the effect-point ...which is, last I
          looked, in lovely

El Segundo, CA which, being shrouded in thick fog,  is not
          currently available for comment.
richard -dot- dimock -at- elsegundoca -dot- attgis -dot- com