Re: On-line documentation vs Hard copy

["Brierley, Sean" <Brierley -at- QUODATA -dot- COM>]

Hallo:

How much time do you have and what are your resources?

I write about software, mostly. I envision four documents:

A hardcopy reference book that describes the features, options, toggles, and
how and why to use them.

An application book that describes the software through its use. This would
include examples of how to accomplish important tasks in the software.

An on-line book. This would be an Acrobat version of the reference and/or
application guide. The structure of this book would be similar to the
printed documentation. PDF has the advantage (versus HTML, for example) of
existing as only one file. It is printable in its entirety or through a page
range. Cross-references, TOCs, indices, etc., can become hypertext. Also,
color is free!! PDF is also a common standard (at least in the US and versus
the few Java Applets that accomplish a similar task) and on-line books can
be updated simply by the customer downloading the new file, which is much
cheaper than updating printed documentation.

An on-line help file. This is a WinHelp or HTML help file that is chunked
and provides appropriate reference information to answer the question "how
do I use this feature, I'm stuck, I need the answer within the next 30
seconds." Unlike the on-line and printed documentation, the on-line help is
not used for pre-planning or reading about a task ahead of time.

Of course, the reality is that I can do three of these. The printed
reference/application combo book gets all the attention and a PDF is
automatically generated after the book is done (actually, I distribute
review copies as PDF, also). Then, as quickly as possible, a help file is
thrown together to ship with the software. This results in a help file that
borrows extensively from the printed documentation and that is not at all
its own project, as it should be. Then, on to the next printed doc . . ..

All the best,

Sean
sean -at- quodata -dot- com

(PS Do you pay relocation expenses?)

>>>-----Original Message-----
>>>From: Bob Gembey [mailto:bob -at- SUPERNOVA -dot- NL]
>>>Sent: Thursday, April 29, 1999 4:26 AM
>>>To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
>>>Subject: On-line documentation vs Hard copy
>>>
>>>
>>>There is a clear trend developing in software products to
>>>minimize the hard
>>>copy documentation provided with a product, replacing it by on-line
>>>versions.
>>>
>>>I don't think that it is satisfactory to take the existing
>>>hard copy manuals
>>>and just add the necessary hyperlinks to allow for jumping
>>>from one topic to
>>>another.  IMHO, reading on-screen and reading a book are different
>>>experiences, and readers have different needs that must be
>>>met.  A manual,
>>>although not a novel, does have a certain continuity in it,
>>>and readers tend
>>>to browse through it looking for information.  On-line they
>>>have other
>>>expectancies, which we must fulfill.  Is it enough to just
>>>provide a search
>>>engine in addition to the electronic index, or a tree-view
>>>to show the
>>>structure of the documentation in addition to TOC's and introductory
>>>sections?  Are there changes we must make to the document content and
>>>internal structure?
>>>
>>>I would appreciate exchanging ideas with others who have
>>>already or are
>>>presently going through this process.
>>>
>>>Bob Gembey
>>>SuperNova Technology
>>>bob -at- supernova -dot- nl

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=