Re: Online Documentation. New! Improved!

["Wing, Michael J" <mjwing -at- INGR -dot- COM>]

<snip>

>I just don't understand why the on-line documentation that came with the apps
>I use is so bad. A lot of it is really dreadful -- much worse than the old
>paper
>docs by the same companies.  My theory is that the dreadful stuff
>comes from people who are slavishly imitating Microsoft and
>each other, rather than learning about on-line documentation from
>the ground up.

And my theory is that product development cycles have sped up (at least
in software).  Many development tasks are no longer linear (first we
develop this, then we develop that).  Instead, many pieces are developed
simultaneously.  Furthermore, development may occur in multiple states
or even multiple countries.

Another complication is reusable code.  A new application may use
functionality for which code already exists. For example, if the new
product for which you are documenting is a terrain analysis application
that also allows annotations, the code for the annotation functionality
could be imported from another application.  This accelerates the
development process.  However, if the documentation for the annotation
functionality does not exist or cannot be easily extracted from the
original application's documentation, the writer is already behind the
pace.

A third complication is flexible development resources.  Often some
developers will be shifted from one project to another to meet current
demands.  If a few developers are experts on raster data programming,
they may be added to a project when raster functionality needs to be
developed.  However, a new writer probably has not been added to the
documentation end.

It appears to me that development has made changes to become flexible in
their resources and accelerated their processes, but many Tech Doc
groups are trying to tread water with slow-to-change (or rigid) document
development techniques and guidelines.  (I'm referring to the medium in
which a document is written and the tools and techniques for presenting
that information not grammar and style).

In earlier days you could document each stage of development as it
progressed.  This provided time to concentrate on writing that one
stage. Had there been online documentation at that time, you would see
better examples of it today.  This is because there would have been more
time to document and the online documentation technology would be a more
mature technology.

Time to market seems to be the major criteria for developing a product.
If development time is accelerating, documentation time better
accelerate.  No project manager or executive is going to be happy if
product release is held back because of documentation!  Therefore, new
technologies such as HTML documents, online manuals, online (context
sensitive) help, multimedia CDs, and information mapping accelerate
document development time.  They also allow for quicker documentation
turn-around time (for updates) and allow the document to be finalized
closer to the ship date (no print shop).  Furthermore, Marketing can
instantly send out preliminary online documents to thousands of
prospective customers.  Up-to-date revisions can be in a customer's
hands in the time it takes them to download and replace the electronic
files (an overnight print shop and federal Express cannot touch this!).

Because time, cost, efficiency, maintenance, and flexibility are major
factors in producing documentation, a Technical Writer's may need to
reevaluate their ascetics.

Mike Wing

_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
_/
_/   Michael Wing
_/   Principal Technical Writer
_/   Infrastructure Technical Information Development
_/   Intergraph Corporation
_/   Huntsville, Alabama
_/   (205) 730-7250
_/   mjwing -at- ingr -dot- com
_/