Notes on electronic delivery of documentation for your information or comment

[Steven Jong <SteveJong -at- AOL -dot- COM>]

I've been asked to recommend a strategy for delivering our documents to
clients electronically. these are some notes I've assembled. I think they may
be of interest to the list; and if you see any errors, your comments will be
of interest to me! 8^)

          -- Steve

================================================================
Steven Jong, Documentation Group Leader ("Typo?  What tpyo?")
Lightbridge, Inc, 281 Winter St., Waltham, MA 02154 USA
<jong -at- lightbridge -dot- com>, 617.672.4902 [voice], 617.890.2681 [FAX]

**************************************************
Electronic documentation is an area of rapid technological advancement, and
confusion over terminology and choices is understandable. Broadly speaking,
user information can be presented electronically in one of two opposing
styles: page images or online information. The two are different in the
McLuhan sense that "the medium is the message." Specific electronic delivery
methods range from revisable form to display-only form (though with enough
effort all presentation formats, even printed pages, can be "reverse
engineered").

In summary, I recommend electronic distribution using either PostScript
format, PDF format, or HTML format, depending on the client's need. However,
we should never again distribute either source files or "snapshot" versions
(a practice that actually disrupts writing and hurts quality), but rather to
release only milestone documents (such as final versions or at least review
drafts).

These options are listed in order, from fidelity to printed pages, and moving
toward pure on-line information.

1) SOURCE FILES -- the files we actually create

PRO:
creation is free (tools on hand)

CON:
needs templates, fonts, linked graphics, maybe printer drivers
(akin to source, compiler, macro library, and environment variables)
(example: one document in our library consists of twelve Word files and 75
linked graphics)
platform-specific, tool-specific, release-specific (e.g., Word 7 files won't
open under Word 6)
easily revised; can't control print quality or speed
gives away proprietary information and intellectual property, exactly as if
we gave away product source code

RECOMMENDATION: absolutely not

2) POSTSCRIPT FILES -- sent to printer; analogous to executable code

PRO:
this is our delivery medium to our print vendor
easily created, tool-independent, cross-platform, widely portable
readable on-screen, more or less, with various readers
unrevisable
creation is free (tools on hand)

CON:
files not compact, sometimes large
can't control print quality
not optimized for on-screen display

RECOMMENDATION: If the client's intent is to reprint and distribute our
documentation, give them PostScript files (though I would rather we get the
reprint revenues ourselves)

3) PROPRIETARY VIEWING TOOL -- uses a freely distributable reader with a
proprietary tool for display of page images
example: Word Viewer for Word files, or FrameView for Framemaker files
(note that we are considering switching from Word to FrameMaker)

PRO:
this method (and all others) easily allows for color
tool-dependent but cross-platform

CON:
Problems with requiring distribution of linked graphics, templates, fonts,
and printer drivers remain
No expertise in house

RECOMMENDATION: For FrameMaker it may become a viable option, but for Word it
is not; further study is required

4) PDF (PORTABLE DOCUMENT FORMAT) FILES -- page images designed for rapid
on-screen display using a free reader
example: Adobe Acrobat ($100 for MS Office users)

PRO:
can be incorporated into Web pages
tool-independent, cross-platform, searchable, printable
unrevisable, but copiable; and still page images

CON:
No expertise in house

RECOMMENDATION: If the client's intent is to make our documents available on
intranets, give them PDF files

The following options are in the realm of on-line information:

5) WEB PAGES (HTML FORMAT) -- information best formatted for on-screen
display; converted from our documents by a batch translator
example: HTML Transit ($500)

PRO:
can put on our Web site or shared internally
We will have to do this for POPS "WebStation" eventually
cross-platform; tool-dependent, but all tools now can do it
can contain hyperlinks to other Web pages

CON:
No expertise in house
easily copied and revised--not secure
manual work needed to touch up format--it's not clear we can or should do
this for all documents
(not at all clear why we should for our terminal-based products)

RECOMMENDATION: If the client's intent is to create a paperless information
environment, give them HTML files

6) WINDOWS HELP (.HLP) FILES -- on-line help, formatted for on-line display
uses a reader (Windows Help Viewer) that is standard with Windows/W95
(note that Microsoft is trying to move Windows Help authors toward HTML help)

PRO:
expertise in house -- done already for our Windows products
requires a compiler and authoring package, which we have (example: RoboHELP)
can be tightly tied to software (context-sensitive help); can launch
"wizards" and multimedia examples
platform-dependent, unrevisable, essentially uncopiable and unprintable

CON:
our Windows products include both printed and online information, which
differ;
it would be a significant amount of work to reformat existing documents into
Help files
(not at all clear why we should for our terminal-based products)
significantly different approach, not compatible with printed documentation
-- in practice, this requires dual source files, but not worth the effort to
maintain both

RECOMMENDATION:
Not worth our effort for electronic delivery of documentation