Re: Re. Documentation types -- what are the possibilities?

[Sandy Harris <sharris -at- dkl -dot- com>]

Geoff Hart wrote:

> <<Also, how do you meet the mandate for more online
> documentation when you truly feel that the information is best
> presented in hard copy?>>

Give the user the choice. Deliver /everything/ online, make
sure /all/ of it is printable, and provide parts of it in
pre-printed form if you feel that is needed.

I started using Unix in the early 80's. All documentation was
online, all of it was printable, and there was a usable (if
rather odd) cross-reference system. All of that had been
there since mid-70s.

I still consider any computing documentation that does not
meet those basic criteria to be obviously defective.

> ... Anything you can put
> on paper, you can also put online. So you move most of the
> context-sensitive stuff online, where it's most useful, and add in the
> high-level overviews you've provided on paper, and voila: you've met
> the mandate for more online docs. But you've also kept the
> important high-level stuff on paper for those who need printed
> information.

One thing you might use is the Docbook DTD from Oasis (Organisation
for Advancement of Structured Information Standards). This is an
SGML DTD (document type definition) supported by several commercial
tools including Frame, and various free tools. It can output HTML
with nice extras like auto-generated linked table of contents, or
a printable book, or other formats.

For example, the table of contents for O'Reilly's book on Docbbook:

http://www.docbook.org/tdg/html/docbook.html

A more limited technique: use HTML and the free Amaya browser/editor

http://w3c.org/Amaya

The lets you build "book" files which mark files to include with
tags <a rel=chapter href="some_name.html">. Hit the "make book"
button and Amaya will include all these into one big doc, adjust
links as required, and generate a table of contents.