Choose the right tool for creating online help

Like any other development task, building a help system for your applications requires you to select the best tool for the job. In my introductory article, "Choosing the online help format that's best for your project," I detailed the various available help formats. Now, it's time to evaluate help-authoring tools and see what they have to offer.

The mechanics
With several of these tools, you create the content in the tool’s authoring environment (depending on the software, this may be Microsoft Word or a custom solution), use a navigation window to assemble the topics in the order you want them to appear, and then click a button to have the program compile the topics into the help output you specify. Of course, there’s a lot more to it than that, but once you’re past the learning curve, creating a basic help system takes no longer than creating any other kind of documentation.

In fact, some authoring tools can actually reduce documentation development time by supporting single-sourcing. Single-sourcing means that you can turn the same set of help topics into printed documentation and any or all of the various help formats simply by specifying the output. If you need to create both printed and online help, or online help in two formats, these tools will save you time.

Tool comparison
Let's take a closer look at some of the products you may want to check into. The following sections summarize several tools and list the company, URL, cost, output format, and pros and cons of each. Most of the companies offer a trial version of these products for download.

Note that this isn’t a comprehensive list, but rather a summary of the least expensive tools that are also the easiest to learn and to use in creating online help. We'll skip the more costly, training-intensive solutions, such as creating documentation in Adobe FrameMaker and turning it into online help via Quadralay’s Webworks Publisher. While the results may be excellent, these two software packages are pricey and have a steep learning curve.

To give you an idea of the GUI for the tools we'll be discussing, Figure A shows the RoboHelp development window for WebHelp. The windows for Doc-to-Help and AuthorIT will look somewhat similar. That’s the WYSIWIG view; Figure B shows the TrueCode view.

Figure A

RoboHelp WYSIWIG

Figure B

RoboHelp TrueCode view RoboHelp
A lot of technical writers use some version of RoboHelp to create their online help systems because it’s both powerful and relatively easy to use. You can basically just point and click to turn Microsoft Word documents, HTML files, and other types of content into an online help system. If you’re really into it, use the Enterprise edition to get feedback about your application: It can create reports about most-visited pages, most frequently asked user questions, and other information that can help you fine-tune your application.

Company
eHelp

Cost

RoboHelp Office, $899 (This creates all help formats.)

RoboHelp for WinHelp, $499 (WinHelp is the old Microsoft help standard for Windows 3.x applications.)

RoboHelp for HTML Help, $499 (HTML Help is the current Microsoft help standard.)

Enterprise $1,899

Output formats supported
As noted above for each version: WinHelp, HTML Help, WebHelp, JavaHelp, Oracle Help; also printed output in Microsoft Word.

Pros
RoboHelp has a relatively easy learning curve if you’re familiar with using Microsoft Word, and it includes a lot of tools that make it easy to find mistakes and debug problems in your online help system. EHelp offers a 30-day money-back guarantee.

Cons
The product may be expensive if your company doesn’t want to invest in online help; support options are also costly.

Doc-to-Help
Similar to RoboHelp, Doc-to-Help uses a relatively simple graphical interface to help you import documents and create an online help system.

Company
ComponentOne

Cost
Doc-to-Help 6, $499.95

Output formats supported
WinHelp, HTML Help, WebHelp, JavaHelp, Oracle Help; also printed output in Microsoft Word.

Pros
Doc-to-Help offers a relatively easy learning curve. It's less expensive than RoboHelp but has a similar interface and supports use of VB scripts to customize style behaviors. Free support is available for 30 days after purchase.

Cons
There's no multiauthoring support for collaborative environments.

AuthorIT
AuthorIT is a database-driven content management and authoring system that can create print and Web content as well as online help. As a content manager, its Workgroup edition allows collaborative authoring and document security.

Company
AuthorIT Software

Cost

AuthorIT V3 Desktop Edition, $199

Workgroup Edition, $499 per license for one to four users (prices decline for additional licenses)

Output formats supported
WinHelp, HTML Help, JavaHelp, Oracle Help; also HTML 3.2 and XHTML 1.0

Pros
AuthorIT has a reasonable price tab and supports a variety of output formats; it also offers versatility for projects other than online help.

Cons
AuthorIT’s many features and alternative uses can be overwhelming to those who just want to develop online help and lack previous experience with content management tools.

Microsoft HTML Help Workshop
HTML Help Workshop is Microsoft’s authoring tool for HTML Help, its standard help system for the Windows platform. You’ll also hear it called simply Microsoft Help. You can import existing .htm files as help topics for a new project or create new help topics in the HTML Workshop Window, shown in Figure C. If you have an old WinHelp project, you can import and convert it to HTML Help.

Company
Microsoft—you can find information on the HTML Help 1.3 SDK at Microsoft’s HTML Help Start Page.

Cost
Free download; follow the link on the HTML Help Start Page.

Output formats supported
HTML Help

Pros
The price is right and the HTML Help Workshop interface may feel more familiar to Windows programmers than other tools. It's easy to integrate with the Windows API.

Cons
HTML Help Workshop is a plain HTML editor. It has no single-source capability and supports help only for Windows desktop applications. Some features of 1.3 are stale compared to the other authoring tools. Release of version 2.0 has been delayed several times and isn’t expected to be available to non-Microsoft programmers until sometime in 2003.

Dreamweaver with Deva Tools
Deva Tools is a set of extensions for Macromedia’s HTML authoring software, Dreamweaver. Deva allows supports using Dreamweaver for online help by providing navigation tools such as a table of contents and a keyword index. Although you can certainly create online help with HTML without Deva Tools, HTML alone can’t make it look and act like the standard online help users are accustomed to seeing.

Company

Dreamweaver: Macromedia

Deva Tools: Weisner Associates

Cost

Dreamweaver 4, $299 for a single license, $2,399 for a 10-pack

Deva Tools, $199

Output formats supported
Technically, you don’t output online help with Dreamweaver and Deva Tools; rather, you create help that ends up similar to the WebHelp format.

Pros
This is a good set of tools for developers who would rather continue to use HTML instead of learning an authoring tool, and it's an excellent option if you’re already using Dreamweaver; you can use Dreamweaver’s templates and libraries.

Cons
You can create only HTML-based help; you’ll have to do your own cross-browser testing.

The tool is only half the battle
Of course, choosing a tool is really the simple part of all this. Writing online help topics differs in various ways from other documentation projects you may have done:

The usability requirements for online help are much stricter than for printed documentation. For one thing, online help needs to be much more concise. Users shouldn’t have to scroll through a window to read it. If a topic requires more space than a window, you should use techniques such as browse sequences.

By the time users consult online help, they're generally looking for answers to problems. You need to create an effective index and table of contents to help users quickly find what they need.

You'll need to minimize or eliminate graphics. They take up valuable screen space, and users can usually see what they need in the application window itself.

The payoff
An online help system can be a useful complement to printed documentation, and it may even replace printed manuals, saving printing and delivery costs. In addition, users often find online help more convenient and accessible than books and manuals. So although most developers cringe at the thought of having to develop online help, the effort is generally worthwhile. Luckily, a number of tools are available to make the job as painless and efficient as possible.

ZDNet / Techguide / Web Development

Choose the right tool for creating online help

Summary

Events

IBM Technology Conference & Expo 2012 May 22, 2012 One World Hotel, First Avenue, Bandar Utama City Centre, 47800 Petaling Jaya, Selangor

Echelon 2012 June 11 and 12, 2012University Cultural Centre, National University of Singapore

Startup Asia Jakarta 2012 June 7 and 8, 201212th Floor, Annex Building, Wisma Nusantara Complex, Jl. M.H. Thamrin No. 59 Jakarta 10350, Indonesia

MMA Forum Singapore April 23-25, 2012Grand Hyatt Singapore

Email

Talkback

Resource Centre Useful content from our premier sponsors

Web Development TechGuides

ZDNet Asia Live

Keep up with ZDNet Asia

Whitepapers

Downloads

Web Development News

Inside ZDNet Asia

Sponsored

Services

IBM Technology Conference & Expo 2012
May 22, 2012

One World Hotel, First Avenue, Bandar Utama City Centre, 47800 Petaling Jaya, Selangor

Echelon 2012
June 11 and 12, 2012

University Cultural Centre, National University of Singapore

Startup Asia Jakarta 2012
June 7 and 8, 2012

12th Floor, Annex Building, Wisma Nusantara Complex, Jl. M.H. Thamrin No. 59 Jakarta 10350, Indonesia

MMA Forum Singapore
April 23-25, 2012

Grand Hyatt Singapore