Building a Help System (HTML Files)?

Subject: Building a Help System (HTML Files)?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, Susan Steen <susan -dot- steen -at- lydiantechnology -dot- com>
Date: Wed, 01 Nov 2006 08:07:52 -0500

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:
- Save the macro in 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 <> 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 -dot- ca

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

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


WebWorks ePublisher Pro for Word features support for every major Help format plus PDF, HTML and more. Flexible, precise, and efficient content delivery. Try it today!

Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.


Previous by Author: Re: "Gaming" interviews (was Future Trends in Technical Writing)
Next by Author: Copyright comic book
Previous by Thread: Re: Building a Help System (HTML Files)
Next by Thread: Negotiating

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

Sponsored Ads