Building a Help System (HTML Files)?

[Geoff Hart]

Susan Steen wondered: <<Currently at my company, we deliver PDF files  
for all of your product documentation.>>

Ack, ptui. <g> Glad to hear you're moving to online help instead...  
much kinder to the long-suffering user.

<<can anyone recommend the following? Utilities or applications  
(free, of course) that can convert a user guide of 100+ pages into  
individual HTML files>>

Since you're already working in Word, simply use Word's own "save as  
HTML" feature. It produces moderately ugly HTML code, but it's  
trivially easy to clean it. Here's how:
- Open the HTML document and save it as a _Word_ file so you can use  
Word's macro features. You can also edit the file as a text-format  
file (which HTML already is), but I believe that some Word features  
aren't available when working with text.
- In a separate document, make a list of all the HTML atrocities you  
want to eliminate or fix. These are typically things like extraneous  
Font tags that have a very simple and repetitive patterns--and are  
thus easy to search for and replace.
- Record a macro that watches as you do a global search and replace  
for every one of those "things what must be fixed". If you simply  
want to delete a tag, leave the "Replace with" field blank. Learning  
to use wildcards will make the macro much more powerful. For a great  
lesson on advanced search and replace, check out the Editorium guide:  
http://www.editorium.com/ftp/AdvancedFind.zip
- Save the macro in Normal.dot or specify that it should be available  
to all documents on your system when you save it.
- When all your editing is done, save the file ("Save as") as a text- 
format file with an .htm or .html extension so that Word doesn't add  
any junk to the file... which it will helpfully try to do if you  
choose HTML format again.

 From now on, all you need to do is run the macro (one click!) and  
you'll quickly produce reasonably clean HTML. As you discover new  
Word-induced HTML problems, add them to the macro.

The larger issue is that the structure of a paper document (PDF) does  
not necessarily map well to the structure of an online document  
(HTML). For one thing, you'll have to specifically break the file  
into discrete topics that map to the parts of the software they  
explain. You'll already have done this to some extent in designing  
the chapters and sections of the print document, but you'll need to  
go several steps farther to ensure that each topic can stand alone;  
in print, we often assume (consciously or otherwise) that readers  
have seen the previous and subsequent pages, but that's no longer  
true in online docs. For example, you'll have to build in lots of  
"see also" references in the online version that would be obvious  
(because some of these sections are visible on the same two-page  
spread) in the print version.

<<Freeware applications that compile HTML help and output as a .chm  
file>>

Microsoft's HTML Help Workshop is the obvious choice, but you'll find  
that buying a more professional tool repays its investment in terms  
of increased ease of use and increased productivity. As I noted  
earlier this week, check out <http://hat-matrix.com/> for a great  
tool that lets you compare the various available options.

<<Integration tips on how to integrate the HTML files or .chm file  
into a Java-based application.>>

Can't help you (haven't worked with Java), but there are many here  
who can.

<<Context sensitive help will be phase 2 or phase 3 of this  
initiative.>>

You'll make your life much easier if you make it part of phase 1 of  
this initiative. It really doesn't add much overhead to the work, and  
if you don't design to allow this right now, you'll have to do it  
later, when it's much harder. Do it once, correctly, right from the  
start, and make it part of your thought process henceforth. You'll be  
glad you did.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --

Geoff Hart   ghart at videotron.ca

(try geoffhart at mac.com if you don't get a reply)

www.geoff-hart.com

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -