Re: Manuals on CD-ROM

[Kent Newton <KentN -at- METRIX-INC -dot- COM>]

A week ago, I posted on this list that the company I work for was
planning to convert its paper documentation to CD-ROM, and I asked the
list members for any advice, suggestions, or insights.  Seventeen people
responded. Two mentioned they were going through the same process and
asked me to pass along any information I discovered; fifteen offered the
information I sought and asked me to keep them posted on the results of
my research.  So...I thought I'd compile the information and present it
to the list.

The responses ranged from a single paragraph telling me what the
respondent's company did to a multiple page list of suggested tools for a
variety of development platforms with guidelines for selecting the
correct tool and suggestions on how to proceed.  The information falls
into these categories:  Tools the Respondents Use, Lists of Available
Tools, and General Considerations.

TOOLS THE RESPONDENTS USE
 -----------------------------------------------

Of the fifteen people who responded, two had not yet undergone the
transition from paper to CD-ROM and six did not mention the product they
themselves were using.  The seven who did identify the products they were
using break down like this:

> PDF files and Adobe Acrobat (5 users)
> FrameMaker and FrameViewer (1 user)
> SGML and DynaText (1 user)
> WinHelp 4.0 (1 user)

(Note:  This adds up to eight users because one respondent uses two
tools: one for third-party documentation that she distributes and one for
her own documentation.)

LISTS OF AVAILABLE TOOLS
 -----------------------------------------

In addition to identifying the tools that the respondents actually use,
several took the time to identify other tools that are available.  Some
also listed advantages and disadvantages of the tools they mentioned.
 (Note that these are the advantages and disadvantages as the respondents
perceived them: others might not agree with the assessment.)  This list
is in descending order of references.

Adobe Acrobat (9 references).  Adobe Acrobat is, by far, the leader.
 Even those respondents who do not use it mentioned it as a possible
tool.
Advantages: you can use the files on CD-ROM and the WWW (Netscape plans
to bundle Acrobat Reader), you can use postscript files from any writing
tool, you can build hypertext links and TOC inside of Acrobat, you can
add on-screen color, you do not have to ship source files, you can view
the document on screen or print it, you can distribute Acrobat
Reader/Viewer free of charge, and it can be used on PCs, Mac, and Unix.
Disadvantages: Acrobat Pro costs about $700 above the cost of your
writing tool, it has the same usage restrictions of paper manuals, it is
difficult to read because of its print-oriented output, and the PDF files
are "big.  Really big."
Additional Resources:  http://www.adobe.com (Adobe home page),
http://www.adobe.com/Acrobat/Acrobat0.html (Adobe Acrobat page),
http://w3.ag.uiuc.edu/AIM/SLOAN/tutorials/Acrobat/index.html (Acrobat
tutorial).

SGML and DynaText (4 references).  This is the distant second leading
option. While only one respondent said he used it, three others mentioned
it as a viable option--especially if we plan to distribute our documents
on the web.
Advantages: it is cross platform (virtually any tool and platform, like
Acrobat) and cross media (WWW, print, postscript, CD-ROM, again, like
Acrobat).
Disadvantages:  none cited.
Additional Resources:  http://www.brainlink.com/~ben/sgml (introduction
to SGML), http://www.arbortext.com/wp.html (getting started with SGML),
http://www.ebt.com (Electronic Book Technologies home page for DynaText),

comp.text.sgml (SGML newsgroup).

Interleaf and World View (3 references):  This is the third leading
option.  None of the respondents used it, but one did say that his sister
company used it, and he warned me to steer clear of it "like the plague."


Advantages:  available on multiple platforms.
Disadvantages: difficult to use.
Additional Resources:  http://www.ileaf.com/wvds.html (Interleaf World
Viewer)

FrameMaker and FrameViewer (2 references).  This tied for the fourth
leading option (with IBM BookManager, below).
Advantages:  No additional cost to develop the files; provides the user
with the book, viewer, and installation instructions in one package; you
use one tool to write the documentation, print paper manuals, and develop
the electronic manual; provides users with the source files that they can
use to develop their own training manuals or customer-specific user
manuals (could also be a disadvantage -- it depends on your point of
view); and works on Mac, PC, and Unix.
Disadvantage:  either you must pay a per-use distribution fee for
FrameViewer or the user must download a royalty-free version of
FrameReader from Adobe.
Additional Resources:  1-800-U4-FRAME (sales line),
http://www.frame.com (Frame home page),
comp.text.frame (Frame newsgroup)

IBM BookManager (2 references).  This tied for the fourth leading option
(with FrameMaker/FrameViewer, above).
Advantages:  none cited.
Disadvantages:  restricted to IBM mainframes and mid-range computers.
Additional Resources:  none cited.

Word and Media Viewer (1 reference).  Tied for last place.
Advantages:  works on Mac or PC.
Disadvantages:  works only on Mac or PC.
Additional Resources:  http://www.microsoft.com/devnews/mvw1_41.htm.

Word and Word Viewer (1 reference).  Tied for last place.
Advantages:  works on Mac or PC.
Disadvantages:  works only on Mac or PC.
Additional Resources:
 http://www.microsoft.com/msoffice/freestuf/msword/download/viewers/

WinHelp 4.0 (1 reference).  Tied for last place.
Advantages:  none cited.
Disadvantages:  works only on Windows.
Additional Resources:  none cited.

DynaWeb (1 reference).  Tied for last place.
Advantages:  none cited.
Disadvantages:  none cited.
Additional Resources: http://www.ebt.com (Electronic Book Technologies
home page)

Envoy (1 reference).  Tied for last place.
Advantages:  none cited.
Disadvantages:  none cited.
Additional Resources:  none cited.

SmartText (1 reference).  Tied for last place.
Advantages:  none cited.
Disadvantages:  none cited.
Additional Resources:  none cited.

OpenText (1 reference).  Tied for last place.
Advantages:  none cited.
Disadvantages:  none cited.
Additional Resources:  none cited.

Folio (1 reference).  Tied for last place.
Advantages:  none cited.
Disadvantages:  none cited.
Additional Resources:  none cited

MS Viewer (1 reference).  Tied for last place.
Advantages:  none cited.
Disadvantages:  none cited.
Additional Resources:  none cited.

KnowledgeSet Retrieval Systems (1 reference).  Tied for last place.
Advantages:  none cited.
Disadvantages:  none cited.
Additional Resources:  none cited.

GENERAL CONSIDERATIONS
 ------------------------------------------

In addition to mentioning the available tools, several respondents
provided suggestions on how to decide which tool I should pick.  I've
summarized those remarks below.

1.  Survey your customers to determine how they use the software, what
software they use, what platforms they use, and what they would like to
see on a CD.  This information will help you develop a product the
customers will actually use.

2.  Determine whether you are restricted to developing the documentation
on a specific system or platform.  This will dictate which tools you can
select.

3.  Decide whether you want to make source files available or restrict
users to view-only files.  This will dictate which tools you can use.

4.  Determine your development cycle, processes, and budget.

5.  If you translate your manuals, determine whether you want to provide
translations on CD and whether the tool you want to use is available
world wide.  This could knock a contending tool out of the running.
 (Don't commit to providing translations on first CD.)

6.  Determine whether the CD will be the only source of information or
whether there will be additional sources such as on-line help or paper
manuals.  This will help you decide the final form of the documentation
on the CD  (electronic copy of paper manual or multimedia on-line
system).

7.  Determine whether the CD will be run from the CD drive or installed
on the hard drive and whether it will be used locally or over the
network.

8.  Determine which development steps you will do (writing, linking,
etc.) and which steps you will send to a third party (pressing the CDs,
distribution, etc.).

9.  After you've narrowed your selections, create and distribute several
prototypes and survey your customers to determine which ones they like
and why.  While you are developing the prototype, document the process
with each tool to compare pros and cons.  Weigh the customer's likes and
dislikes against the development processes to determine which tool you
will ultimately use.

10.  If possible, pick a tool that will provide output in a multitude of
media (print, CD-ROM, WWW) so you reduce the development costs by
preparing for future distribution needs.

I also received suggestions on how to proceed once I've selected the
tool.  In general, the suggestions were to take a phased approach.

Phase 1:  Release your current documentation in view-only format on CDs.
 This is a major accomplishment in itself.

Phase 2:  Spice up the current documentation with hypertext links,
hypertext TOC, and hypertext index and release that iteration.

Phase 3:  Redesign the manual for on-line viewing.  This will be the most
difficult, time-consuming phase because it requires you to break the
linear way of thinking and use a web structure, which requires a total
reorganization of the way you view documentation.

Finally, I received several general comments about moving to on-line
documentation and CD-ROM distribution.

1.  It will save your company money since pressing and shipping CDs is
less expensive than printing and shipping paper documentation.

2.  Switching to CD-ROM-based documentation will take a major culture
shift for both your readers and your company.  It will require the
support of both your company's management and your customer's management.

3.  Even when customer's receive CD-ROM documentation, they will, on
average, print 3 to 4 documentation sets each year (usually piecemeal).

AFTERWORD AND ACKNOWLEDGMENTS
 -----------------------------------------------------------

If you've made it to this point, thank you.  I apologize if this post too
large.  I received a lot of responses and I tried to boil it down as best
I could, but I felt that this topic is valuable to all of us and wanted
to share the information I received.  I hope you found it as valuable as
I did.

To the fifteen people who responded to my post, thank you.  Several of
you not only sent one message to me, but you took additional time to
follow up with additional information when I had questions or when you
discovered more information after your initial post.  I appreciate your
extra effort.  If I misrepresented any of your comments (or if I
plagiarized your words), I apologize.

Finally, I want to comment on how helpful the people on this list are.
 I've been mostly isolated in my profession, and it's been refreshing to
be able to communicate with others in my trade.  It is heartening to know
that I am not alone in the trials I (we) face in trying to develop
documents that our users find clear and helpful.  I enjoy the discussions
and I look forward to participating as my time, resources, and knowledge
allows.Kent Newton
Senior Technical Writer
Metrix, Inc.
kentn -at- metrix-inc -dot- com