HTML Guides?

Subject: HTML Guides?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, Heidi Colonna <mahalapoo_cliff -at- yahoo -dot- com>
Date: Sat, 08 Apr 2006 11:10:55 -0400

Heidi Colonna reports: <<Our shop is planning (in the near future) on moving from .pdf guides, mostly user guides, to HTML user guides. In doing some research online, it appears that HTML guides are not all that different from online help systems as far as the chunking of information/topics. The only major difference I've noticed is that in help systems you have a TOC and in an HTML guide you have a list of links.>>

It's a bit more complicated than that. At its core, the information is identical, as is much of the interface--that is, both are a series of pages (topics) reached by links and cross-references. So pretty much anything you can do in one format, you can do in the other, with varying degrees of ease. In what follows, I'll say "HTML" when I mean a tool such as DreamWeaver; in contrast, Help and HTMLHelp mean the Microsoft formats.

In terms of the technology, Help files are most often a compiled format, usually restricted to a single operating system (or when they're nominally cross-platform, they're typically suboptimal on other operating systems), whereas HTML can be made fully cross-platform with minimal effort--you just have to write to the standards and keep it simple instead of using all the bells and whistles your users don't need. You also won't get a search function built-in with HTML, and will have to find one and add one, or figure out how to link the pages to your operating system's search tools.

In terms of the content, the TOC difference isn't really a difference. A compiled Help TOC may be automatically generated, and may automatically support a collapsible/expandable tree of topics, but you can do the same in HTML. (_I_ can't, but I've seen it done, so it's just a matter of figuring out how.) A table of contents does not, itself, change--only how you create it and display it. And imho, any help system that doesn't have at least one table of contents (preferably a few, with special purpose ones to meet special needs) is useless.

What's missing in HTML are two main things: First, automatic linking to program features such as dialog boxes is missing from HTML; this means that if you want to create context-sensitive help (and why wouldn't you in this day and age?) you have to manually create topic IDs or comparable identifiers (unless a tool such as DevaHelp* does this for you) and you have to teach your programmers how to link to these topics. Not difficult, let alone rocket science, but not as convenient as using something like WinHelp that is so firmly engrained in programmer culture and programming tools that it's a no-brainer.

* See: (also includes indexing and search functions). Windows-only, unfortunately, so I can't use it on my Mac and thus, can't provide details. Strikes me as a silly choice given that it works via Dreamweaver, which I do have on my Mac. Why not write it in Java so it works on all platforms?

Second, no HTML tool encourages you to create an index as you go. I personally consider a help system useless if it doesn't have a _good_ index, so... Indeed, if you don't research the topic, you won't know that indexing HTML is even possible. DevaHelp includes built-in indexing tools; you can also look up HTMLIndexer ( if you prefer a strong standalone product that focuses exclusively on indexing if you don't want to adopt a full package such as Deva.

<<Some of our guides use information mapping (IM) procedures. In playing with the HTML output of guides with these IM tables, the information mapping tables are lengthy and look bad.>>

That's a problem with your use of the tool, not with the tool itself. Information mapping is ***NOT*** about rigid tables, though a casual glance might mislead you into thinking so. My main criticism of IM has always been not with the philosophy--which is powerful--but rather with the fact that users so often forget this philosophy and start thinking only in terms of tables. If all you have is a hammer...

Instead, IM is, in part, about using the concept of a table (chunking and categorizing and using white space to organize information) to help you structure your data. If you've used the method appropriately, and have focused on dividing up the information appropriately, it should take a relatively minor effort to figure out how to redesign the information to work in HTML.

<<My sense is that as we move to HTML, in our documentation that uses the IM method is going to have to be changed.>>

Not really. The format will have to change, but not the process of analysis used to generate the information that you will present using that format. Moreover, it's ironic that you raise this point given that Robert Horn (the inventor of the infomapping method) was also one of the early "names" in hypertext design*. It seems to me that information mapping should translate logically and very efficiently to online uses if you focus on the philosophy rather than on the tables.

* See, for instance, "Mapping Hypertext: The Analysis, Organization, and Display of Knowledge for the Next Generation of On-Line Text and Graphics" (1990). I believe there's a much earlier book too, but didn't go looking.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
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!.
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo 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 lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.

HTML Guides: From: Heidi Colonna

Previous by Author: Installation - Configuration?
Next by Author: HTML Guides? (Take II)
Previous by Thread: HTML Guides
Next by Thread: Re: HTML Guides

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

Sponsored Ads