Re: Documentation - The Way To Go?

Subject: Re: Documentation - The Way To Go?
From: Mark Baker <mbaker -at- OMNIMARK -dot- COM>
Date: Thu, 12 Nov 1998 10:32:08 -0500

Alan Sismey wrote

>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?
>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

It is unclear what you mean by "online documentation" in the first
paragraph. Most people would consider HTML "online".

The problem with a lot of discussions of online documentation and single
sourcing is that they fail to make a distinction between online delivery of
information and online presentation of information.

You can use PDF for online delivery of of information, but it is printed for
display. Of course, you can view the PDF on screen, just as you can view a
word document on screen, but they are designed for paper presentation. True,
you can make cross references into hot spots, which makes turning pages
easier, but that is hardly designing for online presentation.

If you are looking for online presentation then you must design and
structure you information for online presentation, which is radically unlike
paper presentation. A document is to a web as a novel is to a screenplay.
They can tell the same story, but how they do so is completely different.

I would argue that simply translating a Word document to HTML or PDF for
online distribution hardly counts as single sourcing at all. It would more
aptly be called format migration.

If you want to provide both paper presentation and online presentation, on
the other hand, you are going to need a neutral single source. You might end
up using Word as a component editor, but your system will not be document

Mark Baker
Manager, Technical Communication
OmniMark Technologies Corporation
1400 Blair Place
Gloucester, Ontario
Canada, K1J 9B8
Phone: 613-745-4242
Fax: 613-745-5560
Email mbaker -at- omnimark -dot- com

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

Previous by Author: Job: Technical Writer; Siemens; San Jose, California USA
Next by Author: Re: Moving to HTML, take II
Previous by Thread: Re: Documentation - The Way To Go?
Next by Thread: Thanks for the help, and another question...

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

Sponsored Ads