Re: online documentation for web application

["Rebecca Downey" <rdowney -at- matrox -dot- com>]

Kaya Balke said:
>I need to create online documentation for a web application...I'm wondering
if
>I can write documentation directly in an HTML text editor,
>such as HomeSite, or should I use MS Word (FrameMaker is not in the
>budget) and then convert it to HTML?

I recently finished a project where I had to write raw HTML documents as a
web-based help system. The project forced me to keep the file size as low as
possible. I originally was using Microsoft FrontPage 98, but I had a problem
keeping the image maps client side and keeping the web-bots out of the text.
So I switched to Macromedia DreamWeaver 2 and Allaire Homesite 4.

According to the reviews Microsoft FrontPage 2000 is a great improvement
over their previous versions and thus it may be worth your while to examine
the product. Being a Microsoft Office product, it should read MS Word
documents as a secondary format.

The reason I'm lingering over the graphic-interface-type software is that,
personally, I prefer to concentrate on my writing rather than the HTML code.
I have had no problems working with Allaire HomeSite. It has a reasonable
validator, but the HTML validator at http://validator.w3.org/ has caught
errors Allaire HomeSite has missed.

MS Word does not do a stellar job in converting DOC files to HTML. Instead
of keeping your hierarchy of Headings (Header 1, Heading 2, etc...) it
converts all style tags to their raw elements [FONT FACE="AmeriGarmnd BT"
SIZE="4"][/FONT] for example. This includes your body, bold and other style
tags as well as the headings. It does, however, close all tags that it opens
(including the list and paragraph tags), which is a rare feature for an
automatic-html-generator.

Note: I've used [] in the above example to assure that everyone reading this
document can see the tags. In HTML, [] would be replaced by the greater than
and less than symbols ( <> ).

If you want to use MS Word, you may need to touch up the HTML after the
conversion. The various font tags will display the text in the same way you
see it on your screen in MS Word. Unfortunately such font tags may lead to
problems if the person viewing the page does not have the listed-fonts on
their system. And if, like me, you're restricted by a maximum file size,
these extra tags are just wasted space.

I hope this helps.
--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*
R. Downey
Matrox Electronics System (Networks Division)
1055 St-Regis Dorval, Quebec Canada, H9P 2T4
Email: rdowney -at- matrox -dot- com
Web  : http://www.matrox.com/networks