Documentation - The Way To Go?

Subject: Documentation - The Way To Go?
From: Alan Sismey <asismey -at- FNS -dot- COM -dot- AU>
Date: Thu, 12 Nov 1998 11:02:42 +1100

We are looking at a complete revision of our documentation and I would
appreciate any feedback about the best path to follow. I know that aspects
of this issue have been raised in a number of other threads but I don't
believe that our particular situation has been covered.

Our company sells, installs, customises, implements and supports a
financial software package. The customer base covers many countries
including Australia, Philippines, Taiwan, Saudi Arabia, South Africa, South
Korea, Norway and Fiji and we have staff in all of these places. Our target
audience encompasses sales people, business consultants,
analyst/programmers, trainers and includes client staff as well as our own
staff and contractors.

Our documentation is in Word documents, we now use Word 97 though some of
the documents are Word 6.0/95 and all documents have been converted from
Wordperfect. All of the 100 plus documents are standalone and we do not use
the Master Document feature. There are 12 different types of documents and
the size of documents varies from 10 pages to over 200 pages. The system
has an optional GUI front end though all screens are presented in the User
Guides in a 'raw' text format, and this will not change in the short term.

We will continue using Word as our documentation base and also want to
create HTML files for access via Intranet with, possibly, online
documentation as an interim step. We will give our Word documents a new
look, include hyperlinks and eliminate, or at least reduce, redundant

Our use of MS Word as our source documentation is a given and we also use
MS anything else, though it may be possible to use other appropriate tools
or packages. We will not be providing online help though it could be used
for the system's front end components at a later stage.

I believe that a number of packages (such as HDK, Doc-to-Help, Robohelp)
can provide online documentation and also convert into HTML format.
However, what is gained from providing online documentation and is it
necessary when the users will have access to the documentation via Word and
the Intranet? If we chose the online documentation route does any one of
the above packages stand out? Which would provide the most seamless
interface? Which would be the best tool for converting to HTML files?

What other alternatives are there? I have used a trial version of HTML
Transit which seems to provide a good method of converting Word files into
HTML, but naturally it skips the online documentation step. Are there other
tools or packages that could be used?

I know that there is the possibility of using PDF files though our
preference is to use HTML files. There is also quite a lot of information
available about Winhelp, HTMLHelp and JavaHelp but it would seem that if we
took the package approach this is largely irrelevant.

To summarise we want to have single source documentation with MS Word as
the source and with the documents available via Intranet and possibly
online documentation. Any suggestions or comments will be gratefully

Alan Sismey
Email: asismey -at- fns -dot- com -dot- au

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

Previous by Author: Re: ANON: CHAT: How times have changed (reply)
Next by Author: The myth of the "Very dangerous new Virus"
Previous by Thread: Tech Writing, HR, and Recruiters Thereof
Next by Thread: Re: Documentation - The Way To Go?

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

Sponsored Ads