Project Management

Choosing the online help format that's best for your project

No developer wants to work on online documentation, but it is a necessary evil. This article explores the concept of developing online help and describes the available help formats.


If you develop applications that ship with printed documentation, you might want to consider adding an online help system. The conventional wisdom about online help versus printed manuals is that it reduces printing and delivery costs and that it can be easier for users to find and access. Although this isn’t true in every case, an online help system is often a useful supplement to print and, if done correctly, can even replace printed manuals. In addition, usability studies have shown that users are more likely to consult the documentation if it’s accessible from their Help menu than if they have to search for a book.

In this article, I’ll detail the most commonly used help formats and show you how to analyze your project to determine which format is right for your application.

Anatomy of an online help system
The traditional online help system displays a table of contents, an index, and possibly a search function in the left pane of a window and the help topics on the right side. Ideally, the online help window is separate from the application, and that window is sized and placed on the screen so that users can continue viewing the application window as they access help.

Online help can also be context-sensitive. This means that if the user chooses Help when looking at a specific screen, the help system opens to a topic pertaining to that screen. Most authoring tools support context-sensitive help if you map ID numbers correlating the application window to the help window, but it’s an extra that you can do without if you don’t have a lot of time.

How do you create online help?
You can create online help in several ways:
  • You can use one of several online help development tools currently on the market, such as eHelp’s RoboHelp or ComponentOne’s Doc-to-Help. These tools combine word processing and behind-the-scenes formatting to create help systems in any of several formats. To create online help specifically for Windows desktop applications, you can use Microsoft’s help authoring tool, the HTML Help Workshop. Other tools support the Microsoft format as well.
  • You can employ a custom approach by creating your own HTML or XML pages and either link to them from your application or place all the files on your user’s PC.

The best approach for you depends on the type of application you’re developing and the amount of time you have available. Chances are good that one of the commercial help applications will suit your needs. You can find a tool that’s relatively inexpensive and offers a short learning curve for anyone familiar with word processing. In my next article, I’ll compare the help authoring tools currently on the market.

I offer the custom HTML approach as a “good enough” method for rushed developers who don’t want to take time to learn a new tool. But because HTML alone doesn’t offer the kind of standard help that users are accustomed to seeing or organizational tools such as an index or search function, it’s difficult to provide comprehensive help this way. Consider a strictly HTML approach if an FAQ-type format is sufficient. If you’re willing to test all the cross-browser compatibility issues, you could use framesets and DHTML or JavaScript to create a dynamic table of contents and other typical help functions.

Of course, you can create your own custom help application using any of several languages or tools. However, you’ll have to learn how to create the kind of help familiar to users and how to make it work with whatever is on their desktops.

Choosing the right help format
The help output format you choose for your project will depend mainly on the application accompanying the help and the environment in which it will be used. The following sections detail the output formats used to create online help. I’ve summarized each one and noted what type of file the finished help system is packaged in. Some help authoring tools allow you to choose any of these formats, while other tools can create help in only one format.

WebHelp
WebHelp is an HTML-based format that’s designed to work on all popular browsers. It’s also the only help format that does run in a browser, and thus it’s the choice for providing server-based help. WebHelp consists of HTML files in a folder that you can install on the user’s PC or place on a server for easy maintenance. The advantage of using WebHelp over creating your own HTML-based help is that you don’t have to do the cross-browser testing yourself. Obviously, users need a browser to access this type of help.

To give you an idea of what this looks like, Figure A shows an example of some simple help system output in the WebHelp format and displayed in Internet Explorer. I created this system by using eHelp’s RoboHelp authoring tool with all the default settings. You can customize a lot of the elements you see here, such as the blue background.

Figure A
WebHelp output


HTML Help
HTML Help, also called Microsoft HTML Help, is the Microsoft standard for help. It’s HTML-based help designed for use with 32-bit Windows applications, such as Windows desktop apps. The output is one compiled file (.chm) that runs locally in an HTML Help window.

Figure B shows the same help system from the previous figure compiled into the HTML Help format. An advantage of HTML Help over WebHelp is that the compiler compresses the files; this small project was 855 KB as WebHelp but only 35 KB once compiled into HTML Help.

Figure B
HTML Help output


WinHelp
WinHelp is the original Windows help format, initially used for writing help for 16-bit Windows applications. It runs on 16-bit and 32-bit applications in the original WinHelp window, which is provided with those apps. You won't use this format unless your users are running Windows 3.x. The result is one compiled file (.hlp) and one contents file (.cnt) placed on the user’s desktop and run locally.

JavaHelp
The JavaHelp format provides help specifically for Java applications. It should run locally to conform with the Java security model, but you can get around this and run the help from the server if you want to employ custom approaches. Users must have the JRE on their PCs to view JavaHelp.

The output is one or more files, depending on how you generate it: Compressed output without source files results in one .jar file; output with source files results in a HelpSet file (.hs) and the project files. Both run locally.

Note that unless you want JavaHelp to replace whatever your user is looking at in the current window, you may need to use a plug-in to launch JavaHelp in a browser window.

Oracle Help
Oracle Help also provides help for Java/Oracle apps and should run locally. Users must have the JRE installed, and the output is the same as the options discussed for JavaHelp.

Analyzing your project
As you can see, the world of online help encompasses as wide an array of options as other development endeavors. You can narrow down your options by analyzing your goals and the project at hand. When considering the appropriate type of help, assess the following factors:
  • The application you’re providing the help for
  • The needs and experience levels of end users and the environment in which they'll be accessing the help

Your application
First, look at your application. If it's a Windows 3.x application, you'll have to use the older WinHelp format. If you’re developing help for a Windows desktop application and know that users will have Internet Explorer, it makes sense to create HTML Help. But you don’t have to do so—you could just as easily use the cross-browser WebHelp format.

If you’re developing a custom application and don’t have any control over the user’s browser, WebHelp is often the best choice. WebHelp is also the best choice for supporting browser-based applications.

The end users and the environment
In deciding where to place the online help, consider your end users and the environment in which they will be accessing the help. Placing the help on a server—whether on an intranet for company employees or an Internet that your users will dial in to—enables you to easily update and maintain the help files. This can be a great option for an intranet, but it may not be so good for Internet users. Although many companies place their documentation on the Internet, having to go online to access it can be inconvenient for some users. Novice users in particular may shy away from using such help or may not even realize that they must have a connection to access it. If you decide to go with server-based help, you’ll need to use the WebHelp format.

If installing locally, consider that HTML Help produces one compact file, while WebHelp requires a file-intensive approach—and users could delete what they perceive as useless .htm files that take up a lot of space.

In my next article, I’ll follow up with a look at help authoring tools, including manufacturer contacts, price information, and the pros and cons of each.

Editor's Picks