Wednesday, May 2, 2007

HTML Help vs. WebHelp

A classic question when creating online help or documentation is what output format to use, HTML Help or WebHelp? It’s important to pick the most appropriate format for your project. Fortunately, modern authoring tools are flexible enough that you can change the format during a project if you picked the wrong format when you began.

HTML Help

HTML Help is a format from Microsoft, and the successor to the older Windows Help, or “WinHelp,” of the late ‘80s and early ‘90s. Microsoft created HTML Help around ‘95 and introduced in February, ‘97. This means that HTML Help effectively predates the web, and it shows.

HTML Help is “compiled” – all the files that make up a finished help project – the topics, graphics, and control files – are contained in one file with a CHM extension that gets distributed to the users. So if you have one topic, you get one CHM file. If you have one thousand topics, you get one CHM file…

HTML Help’s Technical Requirements

HTML Help has three requirements:

Platform - It only runs under Windows. It won’t run on a Mac, Linux, Unix, etc.

Browser - It only runs under Internet Explorer (IE). IE need not be the default browser, but it must be on the user’s PC.

Location - It can only run “locally,” on a drive on the user’s PC. It was not designed to run on a web server but, until recently, could run on a network drive. However, security patches to Windows and IE now largely prevent this.

Pros and Cons of HTML Help

On the pro side:

Standard interface - Although developers can customize the interface, the basic interface is always the same – a toolbar at the top of the screen, three navigation tabs (Contents, Index, and Search) at the lower left, and the main topic at the lower right. So once users learn how to use one CHM, they know how to use them all.

Distribution - Simple. Just send the CHM.

Security - The CHM is compiled, and thus “closed,” so users can’t alter the text.

On the con side:

Outdated - The CHM looks proprietary and dated compared to the webbish look that today’s users are accustomed to.

The future - HTML Help’s use of HTML puts its technical future in question as XML begins to dominate. Microsoft could fix this by upgrading HTML Help, but Microsoft has been trying to move past HTML Help for years. Microsoft tried to replace it in the early ‘00s with a format called Help 2.0, but Help 2.0 never took off. Vista, the new version of Windows, has its own XML-based help format and, as Vista begins penetrating the market, Microsoft seems likely to shift resources away from HTML Help.

Confusion - The name “HTML Help” can be confusing. Listeners may think you said “HTML help”, which is not the same as “HTML Help.” The latter is a formal format, but the former is simply any web site that offers help and is written in HTML. I saw one project that got derailed for ten months because of this confusion. Be certain that your listeners understand that you mean “HTML capital-H Help.”

WebHelp

WebHelp was originally created by eHelp, the original maker of RoboHelp, in early ‘98 in response to the limitations of HTML Help. Today, every help authoring tool has some version of WebHelp.

WebHelp is “uncompiled HTML” – all the files that make up a help project – the topics, graphics, and control files – remain as individual files within an output folder that gets distributed to the users. So unlike HTML Help, where you always have one distributable file, you’ll wind up with dozens, hundreds, or even thousands of files with WebHelp. In effect, WebHelp is just a web site oriented toward online help and documentation.

WebHelp’s Technical Requirements

WebHelp’s requirements are basically the opposite of HTML Help:

Platform - It runs on almost any modern platform – Windows, Mac, Linux, UNIX, etc.

Browser - It runs on almost any modern mainstream browser – IE, Firefox, etc.

Location - It can run locally, on a drive on the user’s PC, but also from a web server or network drive.

Pros and Cons of WebHelp

On the pro side:

Webbishness - WebHelp looks like, and in fact is, a web site. So users will find it easier to learn because it will look familiar.

Vendor-independent - WebHelp is not tied to one vendor, the way HTML Help is to Microsoft. There’s less risk of your help format suddenly becoming unsupported.

Flexibility - The almost unlimited platform support, browser support, and file location offers almost unlimited distribution flexibility.

On the con side:

Distribution - Simple because there’s only one folder to distribute, but that folder may contain hundreds or thousands of files, which will make your network people unhappy. However, the fact that each topic is a separate file means that users are downloading smaller files than they are with HTML Help, thus reducing the load on your network.

Security - Because WebHelp is uncompiled, and thus “open,” users could alter the text in a topic file. This may be a serious risk.

So which Format Should You Use?

You’ll want to take your own specific requirements into account but, in a nutshell, use:

WebHelp if you need the distribution flexibility and the webbish look.

HTML Help if you need a pre-Vista Microsoft-standard look or want to “lock” the help to prevent users from modifying the content.