Electronic delivery of documentation: final memo (long)

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

[Thanks to those of you who commented on (or edited!) my notes on electronic
documentation delivery.
For your information I append the memo as I sent it. As before, I hope you
find this information useful.]

          -- 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]

Recently we have struggled to satisfy client requests for electronic document
delivery. The root cause is apparently confusion (usually on the client's
end) over what delivery format will satisfy the need. We expect more requests
in the future. This memo outlines choices and offers recommendations for
electronic delivery of our existing user information, with particular
reference to information protection and ease of creation.

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 (electronic delivery for printing) or online information
(electronic delivery for online viewing). The two are different in the
McLuhan sense that "the medium is the message;" the presentation is best if
tailored for the delivery method. Specific electronic delivery methods range
from revisable form (no information protection) to display-only form (strong
information protection), though with enough effort all presentation formats,
even printed pages, can be "reverse engineered."

In brief, I recommend electronic distribution using either PDF format,
PostScript 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 schedules and hurts quality). Instead, we
should release display-only documents, and then only milestone versions (such
as final versions or at least review drafts).

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

1) SOURCE FILES -- These are the files we actually create that are assembled
into documents. Examples are Microsoft Word files or Aldus PageMaker files.

PRO:

o       Creation is free (we have the tools on hand)

CON:

o       The source files may be complex; for example, one document in our library
consists of
        twelve Word files and 75 linked graphics

o       The client may not have the tools on hand

o       The client may need files plus templates, fonts, linked graphics, or
printer drivers
        (akin to needing source files plus the compiler, macro libraries, run-time
routines, and environment variables)

o       Source files are platform-specific, tool-specific, and release-specific
        (for example, we have had some problems opening Word 7 files under Word 6)

o       We lose control of print quality

o       Source files are easily revised; giving them up abandons our proprietary
information and
        intellectual property, exactly as if we gave away product source code

RECOMMENDATION: We should absolutely not give out source files.

2) POSTSCRIPT FILES -- These are page description files, meant for print
devices;
they are analogous to compiled code.

PRO:

o       This is our delivery medium to our print vendor

o       they are easily created, tool-independent, cross-platform, and widely (but
not universally) portable

o       They are readable on-screen, more or less, with various readers

o       They are unrevisable

o       File creation is free (tools on hand)

CON:

o       Files are not compact and sometimes large (though we can use Zip disks to
distribute them)

o       We lose control of print quality

o       Files are not optimized for on-screen display and may not be legible

o       Files are not searchable

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 -- The client uses a freely distributable reader
with a proprietary tool
to display page images; for example, Word Viewer for Word files, or FrameView
for FrameMaker files
(note that we are considering switching from Word to FrameMaker)

PRO:

o       This method (and all others subsequently mentioned) easily allows for color

o       Files are viewable across platforms

CON:

o       Files are tool- (and viewer-) dependent

o       The client may still require distribution of linked graphics, templates,
fonts, and printer drivers

o       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 -- These are page images designed for
rapid on-screen display
using a free reader; the best creation tool is Adobe Acrobat ($100 for MS
Office users; more for Acrobat Pro)

PRO:

o       Tool-independent (Acrobat converts files from many tools) and
platform-independent

o       Fully preserves original page formatting

o       Files can be incorporated into Web pages

o       Files can contain hyperlinks

o       Files are unrevisable, but copiable

o       Client can search and print pages

CON:

o       No expertise in house (but the learning curve is said to be minimal)

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

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

5) WEB PAGES (HTML FORMAT) -- This is information presented using a Web
browser, and best formatted with
on-screen display in mind; converted from our documents by a batch translator
such as HTML Transit ($500)

PRO:

o       Files can be put on our Web site (internet) or shared internally (intranet)

o       We will have to do this if and when we develop Web-based products

o       Cross-platform display; all tools now can create HTML pages

o       Pages can contain hyperlinks to other Web pages

o       This is the most marketable option

CON:

o       No expertise in house

o       Files are in text (ASCII) format, easily copied and revised -- not secure

o       Hand work is needed to touch up formatting after machine translation --
        it's not clear we can or should do this for all documents
        (and 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 -- This is online help, formatted for online
display
using a reader (the Windows Help Viewer) that is standard with Windows/W95
software
(note that Microsoft is trying to move Windows Help authors toward HTML help)

PRO:

o       We have expertise in house -- we routinely make Help files for our Windows
products

o       We have tools (such as RoboHELP) in house

o       Files can be tightly tied to software (context-sensitive help); they can
launch "wizards" and multimedia examples
        as part of the presentation

o       Files are unrevisable

CON:

o       Help files are platform-dependent

o       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
        (it's not at all clear why we should do so for our terminal-based products)

o       Files are essentially uncopiable and unprintable

o       Online presentation is a significantly different approach, not compatible
with printed documentation --
        in practice, this requires dual source files

RECOMMENDATION: Help and printed documentation have their places, but
converting documents to Help is not worth the effort simply for electronic
delivery of documentation.

OTHER OPTIONS NOT INVESTIGATED

Other possible options, though not investigated, are mentioned here briefly.
Most beg the question of what format to store the files in anyway.

Lotus Notes server

SGML (beyond the scope of our needs; steep learning curve)

Gopher/FTP site (our document sets aren't big enough to justify this)

USENET List Server (too public, too elaborate)

Our own Web site