TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Re: Re. Documentation types -- what are the possibilities?
Subject:Re: Re. Documentation types -- what are the possibilities? From:Sandy Harris <sharris -at- dkl -dot- com> To:TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com> Date:Wed, 03 Nov 1999 10:35:05 -0500
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
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:
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.