Boston Broadside
November/December 2002
Vol. 60,  No. 2
 Newsletter of the Boston Chapter of the Society for Technical Communication

Contents


Copyright © STC Boston 2002

Tools of the Trade

Choosing Help Authoring Tools:
What Are Your Choices?

By Char James-Tanny

Whatever your official title, if you are a Help author, then you use Help Authoring Tools (HAT) and HAT vendors want your business. Whether you have just joined the field, are considered an expert, or are somewhere in between, you face the challenge of deciding which tools to use. Many factors influence your decision. This two-part article explores these factors for some of the more popular HATs available today. Part I provides a comprehensive overview. Part II, which will appear in the January/February issue of the Broadside, will outline the factors to consider when choosing different tools.

What Tools Are We Talking About?

For this article, I discuss the following tools:

  • AuthorIT® (http://www.author-it.com/)
  • Deva Tools (http://www.devahelp.com) and Dreamweaver (http://www.macromedia.com/software/dreamweaver/)
  • Doc-To-Help (http://www.componentone.com)
  • FAR (http://www.helpware.net)
  • HCW (http://www.microsoft.com/downloads/release.asp?ReleaseID=23216)
  • HDK (http://www.virtualmedia.com.au/hdk.htm)
  • HHW (http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp)
  • The HyperText Studio (http://www.olsonsoft.com)
  • Mif2Go (http://www.omsys.com)
  • RoboHelp Office (http://www.ehelp.com)
  • Sevensteps (http://www.sevensteps.com)
  • WebWorks® Publisher (http://www.webworks.com/products/wwp_pro/default.asp)
  • WebWorks® Publisher WordHelp (http://www.webworks.com/products/wwp_wh/default.asp)

ForeFront’s ForeHelp is no longer included in this list. On January 2, 2002, ForeFront went out of business and ComponentOne announced that it had acquired three key technologies from them: InterHelp, MIF import, and Help Server Studio (an unreleased product).

Output

The current list of possible outputs includes:

  • WinHelp 4
  • HTML Help 1.x
  • HTML-based Help
  • JavaHelp
  • Oracle Help for Java

You can also produce printed or PDF output, although the method depends on the tool. For example, if you are developing your project with Adobe® FrameMaker or Microsoft Word, then you will use them to print. Some tools let you repurpose your project to print, including all or selected content. Other tools let you single-source to print, using conditional text to control the output.

The following lists provide features, limitations, and possible HATs for these outputs.

WinHelp 4

  • Runs locally on 32-bit Windows.
  • Compressed and compiled (.hlp), plus CNT for Table of Contents.
  • Navigation includes Table of Contents, two-level index, full-text search, and browse buttons (if enabled).
  • Extra functionality provided by WinHelp macros and DLL files.
  • Windows include Main with menus and buttons, secondary with buttons, and fully-formatted popups.
  • Context-sensitivity provided with map numbers.
  • Modular Help created through the CNT files.
  • Dynamic linking.
  • Limitations:
    • Non-synching Table of Contents without third.party DLL file (for example, eHelp’s WinHelp 2000).
    • Modal navigation.
    • No table borders or shading, limited font formatting.
    • No further development. Bug list maintained by Don Lammers at http://www.smountain.com/m_ref.htm
  • WinHelp Tools:
    • AuthorIT
    • Doc-to-Help
    • HCW
    • HDK
    • HyperText Studio
    • Mif2Go
    • RoboHelp for WinHelp
    • Sevensteps
    • WebWorks Publisher
    • WebWorks Publisher WordHelp

HTML Help 1.x

  • Runs locally on 32-bit Windows.
  • Requires Internet Explorer.
  • Compressed and compiled (.chm).
  • Navigation includes TOC, multi-level index, full-text search or advanced full-text search, Favorites tab.
  • Extra functionality provided by HTML Help controls, ActiveX, JavaScript, VBScript.
  • Windows include tri-pane with menus and buttons, secondary, text-only popups. (Several tools, such as RoboHelp HTML, let you create fully formatted popups.)
  • Context-sensitivity provided with map numbers and aliases.
  • Modular Help created through contents and project files.
  • Dynamic linking.
  • Limitations:
    • Requires at least Internet Explorer version 4.0.
    • Harder to implement secondary windows, as HTML doesn’t provide a mechanism for specifying them in hyperlinks.
  • HTML Help Tools:
    • AuthorIT
    • Deva Tools + Dreamweaver
    • Doc-To-Help
    • FAR
    • HDK
    • HHW
    • HyperText Studio
    • Mif2Go
    • RoboHelp Office
    • Sevensteps
    • WebWorks Publisher
    • WebWorks Publisher WordHelp

Recently, a group of independent consultants collaborated on a project to compare the HTML, CSS, and HTML Help output of several tools. The results include the file sizes of the HTML Help, CSS, and HTML files; the HTML and CSS validation results; and output samples, providing developers with another source of information when comparing tools. Some developers may need to compare file sizes, which affect download speeds for users with dialup access, while other developers may be interested in the validation results. David Knopf of Knopf Online is hosting the results at http://www.knopf.com/resources/hatcomp/index.html.

HTML-based Help

  • Runs on any platform through a browser.
  • Not compiled or compressed, but can be generated.
  • Possible navigation includes TOC, multi-level index, and full-text search, using frames.
  • Browse buttons available through tool or by hand-coding.
  • Add extra functionality with JavaScript and Java.
  • Windows include browser, scripted secondaries, and popups (automated by a HAT).
  • Context-sensitivity provided by linking to the HTML file.
  • No modularity or dynamic linking, unless provided and converted by your HAT.
  • Limitations:
    • Can’t use all online Help features that you might be accustomed to (dynamic linking, WinHelp macros, secondary windows, and more).
    • Some tools use Java, ActiveX, or Dynamic HTML for the TOC.
  • HTML-based Help tools:
    • AuthorIT
    • Deva Tools + Dreamweaver
    • FAR
    • HDK
    • HyperText Studio
    • RoboHelp for WinHelp (WebHelp)
    • RoboHelp for HTML Help (WebHelp)
    • Sevensteps
    • WebWorks Publisher (WebWorks Help)
    • WebWorks Publisher WordHelp (WebWorks Help)

JavaHelp and Oracle Help for Java

  • Runs locally on any system with the Java Runtime Environment (JRE). The only formats designed specifically for Java applications.
  • Includes separate viewer (cannot be run in Netscape or Internet Explorer).
  • Compressed (.jar) or uncompressed.
  • Navigation includes TOC, multi-level index, and full-text search.
  • Browse buttons available through tool or by hand-coding.
  • Extra functionality provided through lightweight Java components.
  • Windows include three-pane with menus and buttons, secondaries, and popups. Oracle Help for Java uses dockable windows.
  • Context-sensitivity provided through topic IDs and URLs.
  • Modular Help available in compiled format (.jar) through the project file.
  • Dynamic linking allowed in development and converted during development, when using a HAT.
  • Limitations:
    • Neither output supported by all tools.
    • JavaHelp uses HTML 3.2-/HTML 4.0+. Oracle Help for Java uses HTML 4.0.
    • No JavaScript.
    • Limited Cascading Style Sheet implementation in JavaHelp.
    • No browser-based linking (unless you don’t need a “pure Java” solution).
  • JavaHelp and Oracle Help for Java tools:
    • AuthorIT (both)
    • Doc-To-Help (JavaHelp)
    • Mif2Go (both)
    • RoboHelp Classic (JavaHelp)
    • RoboHelp HTML (both)
    • WebWorks Publisher (JavaHelp)
    • WebWorks Publisher WordHelp (JavaHelp)

For a summary of the preceding information, please visit my Web site. There, you’ll find a comparison chart including more information on these tools, plus URLs for other tools not mentioned here. If you’re using Acrobat 4, go to http://www.helpstuff.com/downloads/toolsv4.pdf) or for Acrobat 5, go to http://www.helpstuff.com/downloads/toolsv5.pdf).

You can also download a PowerPoint presentation (http://www.helpstuff.com/downloads/HATcomparison.ppt). You’ll notice that to find the optimal solution, you must move between main categories. For example, your users may all use Microsoft® Windows®, but maybe the default browser is Netscape and IE isn’t even installed. In this case, typical Windows solutions (such as HTML Help) may not be an option.

Char James-Tanny has more than 20 years of experience as a technical writer and is well known in the Help community for her knowledge of online Help tools and concepts. Author of two books, she speaks frequently at conferences around the world. Char is a senior member of STC’s Boston Chapter and a 2003 WinHelp Microsoft MV. You can reach her at .

Editor’s Note: Part 2 of this article,” Choosing Help Authoring Tools: What Factors Affect Your Decision?,” will appear in the January/February issue of the Boston Broadside. It will outline factors you need to consider when choosing a Help Authoring Tool.

Broadside in PDF | Print-friendly Article

Resources