Re: Online Documentation

Subject: Re: Online Documentation
From: Sandy Harris <sandy -at- storm -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 02 Nov 2000 16:12:41 -0500

bogucki91030 -at- yahoo -dot- com wrote:
>
> We are considering putting our documentation online.
>
> Do any of you have experience putting documentation
> online?

All of my stuff for my current project is online:
http://www.freeswan.org/doc.html

> Would any of you mind sharing your ideas on how to
> structure it, some common pitfalls, etc.

For any computer product, I'd say /minimum/ requirements were:

all docs available online
all docs printable by user
complete documentation, e.g. all file formats described
usable cross-reference system

Of course I know many products (almost none on Windows) meet those
requirements. On the other hand, Unix already did in the early 80s
when I started using it.

Methinks the big structural issue is how to achieve clarity without
excessive duplication. If the same menu or esoteric term shows up on
23 screens, or if 23 programs access the same file, you don't want to
have 23 copies of the same explanation. On the other hand, you want
the text to be readable without having to open 14 windows or jump
around frantically.

One major pitfall is failure to design or re-design docs for online
use. It is possible to write something that works well both on paper
and online, but just taking your print docs, turning them into PDF
and slapping them on the web site will not do it. Nor will just
grabbing all the files off your web site and printing them produce
good paper docs.

Another is locking yourself into proprietary formats. GNU info
works OK on Linux, Windows help files on Windows. What happens
if you need either doc on the other system? On a Mac?

> I don't know if we should do just FAQ's or the whole
> doc. Also, how is it done? In HTML? XML? PDF's (excuse
> my ignorance!)

I use HTML, then produce table of contents and other output formats
(PDF and Postscript) with the free tool htmldoc from www.easysw.com.

Likely that is not the best method. Certainly it is not what I'd
choose if I were starting a new project. For that, I'd use XML and
the DocBook DTD.

http://www.docbook.org/
http://www.oasis-open.org/docbook/index.html

For examples of large chunks of online documentation, delivered in
multiple formats and produced largely with free tools:

http://www.linuxdoc.org/

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Learn how to develop HTML-based Help with Macromedia Dreamweaver!
Dec. 7-8, 2000, Orlando, FL -- $100 discount for STC members.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Sponsored by SOLUTIONS, Conferences and Seminars for Communicators
Publications Management Clinic, TECH*COMM 2001 Conference, and more
http://www.SolutionsEvents.com or 800-448-4230

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.


Previous by Author: Nice toy for a whirler
Next by Author: Re: giving writing advice
Previous by Thread: Re: Online Documentation
Next by Thread: QUICK! - symbols help


What this post helpful? Share it with friends and colleagues:


Sponsored Ads