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.
bogucki91030 -at- yahoo -dot- com wrote:
>
> We are considering putting our documentation online.
>
> Do any of you have experience putting documentation
> online?
> 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.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
