Boston Broadside
January/February 2003
Vol. 60,  No. 3
 Newsletter of the Boston Chapter of the Society for Technical Communication

Contents


Copyright © STC Boston 2003

Tools of the Trade

Choosing Help Authoring Tools:
What Factors Affect Your Decision?

By Char James-Tanny

Editor's Note: Part 1 of this article, Choosing Help Authoring Tools: What Are Your Choices?, appeared in the November/December issue of the Boston Broadside. It outlined features of different Help authoring tools.

Your Users' Environment

While the other factors play a part in your decision, it's all for naught if your users cannot access what you produce. Consider the following environment issues:

  • Platform. Are your users working with Windows, Mac OS, or some flavor of UNIX? Windows allows for the greatest flexibility when determining an output, as all outputs listed work on Windows. However, Windows-only solutions will not work with Mac OS and UNIX. (Although it is possible to use a Windows emulator with Mac OS or UNIX systems, all users must have installed the emulator.)
  • Operating system. What flavor of Windows do your users have? Depending on the output you choose, you may need to know.
  • Available browsers. Do your users have Internet Explorer or Netscape? Do they use Opera, Mozilla, K-Meleon, or Lynx? Each browser has its pros and cons, and different browser versions mean that you have to consider multiple scenarios. If the company has standardized on Netscape, then Internet Explorer may not even be available (which rules out some outputs).
  • Online access. If you're going to deliver a 'Net-based solution, you may have to consider whether users have 56K modems, T1 lines, or something in the middle.
  • Security. If your users request that nothing additional is downloaded (such as Java applets or ActiveX controls), then you'll need a pure HTML solution.

Your Development Environment

Before considering which output to produce, consider your development environment. Do you already work in Word, FrameMaker, or HTML, or are you planning to switch? Do you use or want to move to a database-driven tool? Are you wondering what else is available?

The following tools use Microsoft Word as their development environment:

  • Doc-To-Help
  • Microsoft's Help Compiler Workshop (HCW)
  • RoboHelp for WinHelp (standalone or as part of RoboHelp Office)
  • WebWorks Publisher WordHelp

If you use FrameMaker, then you can convert the FrameMaker files to an online output with Mif2Go or WebWorks Publisher. In addition, AuthorIT and RoboHelp HTML let you import .mif files. You can design a process where you import the .mif files each time, or you can move from FrameMaker to either of these tools.

To develop in HTML, you can use:

  • Dreamweaver + Deva Tools (or just Dreamweaver)
  • FAR (with an HTML editor)
  • Microsoft's HTML Help Workshop (HHW, with an HTML editor)
  • The HyperText Studio
  • RoboHelp for HTML Help (standalone or as part of RoboHelp Office)

To use a database-driven authoring tool with a built-in word processor, consider:

  • AuthorIT
  • Sevensteps

Output Features

If you need a special feature that overrides all others, then you may need to search a little further. I've listed some features that tend to be requested most often, and, where possible, the tools that support them.

Pure HTML is output that does not use or require Java, JavaScript, or ActiveX. AuthorIT provides pure HTML navigation by default. Other tools, such as WebWorks Publisher and RoboHelp HTML, can be forced to output pure HTML.

Valid XHTML is HTML that meets the requirements of the World Wide Web Consortium (W3C) when analyzed by the W3C HTML Validator. At the very least, to produce valid HTML or XHTML, topic files must include both a valid DOCTYPE and CHARSET statement. None of the tools provide valid HTML "out of the box" (except for Dreamweaver MX). While it is possible to change the output files so that they validate, it means that a) you must know how to code valid HTML/XHTML and b) you must modify the resulting files every time you generate. You must also learn how your tool codes the HTML. For example, RoboHelp HTML uses proprietary Kadov tags, while WordHelp and AuthorIT apply CSS classes to all styles.

Full-text search lets users type words that they think exist in the output. Full-text search can use Java, JavaScript, or CGI. Most tools on this list use JavaScript for full-text search. However, by default, AuthorIT does not include a search tab, although the Help file does include instructions for hooking up a free CGI search.

Natural language query lets users type questions instead of just words (for example, "How do I format a paragraph?" instead of "format paragraph."). None of the tools listed include natural language query, although it is possible to add it with an external tool (such as WexTech's AnswerWorks), or you can use RoboHelp Enterprise to add natural language query to its HTML-based output.

Cost

When it comes to Help Authoring Tools (HATs), you can spend as much or as little as you like. Prices range from free, to inexpensive (less than $300), to mid-range (less than $700), to high-end (more than $700). For the most part, prices do not include support or upgrades, although that varies by vendor.

Note that prices change, which is why I haven't listed them here. You can get more information from the vendor sites. See the URLs in Part 1 of this article, Choosing Help Authoring Tools: What Are Your Choices?, in the November/December issue of the Boston Broadside.

Tools from different vendors that have the same terminology (such as "Enterprise") don't always include the same functionality. For example, AuthorIT's Enterprise Edition uses a SQL Server database, while RoboHelp's Enterprise Edition lets you create server-based WebHelp with natural language query and user reports.

Free tools include Microsoft's Help Compiler Workshop (HCW) and Microsoft's HTML Help Workshop (HHW). Jeremy Griffith of Omni Systems, makers of Mif2Go, has offered a free personal copy of Mif2Go to anyone who is laid off or to any underemployed consultants, with free e-mail tech support and upgrades for life. Visit the Omni Systems Web site at http://www.omsys.com/ for more information.

Inexpensive tools include AuthorIT's Desktop Edition, Deva Tools, FAR, HyperText Studio (Standard and Professional Editions), Mif2Go, and Sevensteps Light.

Mid-range tools include AuthorIT Workgroup and Fixed Enterprise Editions, HyperText Studio Enterprise Edition, Sevensteps Standard, and WebWorks Publisher WordHelp.

High-end tools include AuthorIT's Floating Enterprise Edition, Doc-To-Help, RoboHelp Office, RoboHelp Enterprise, RoboInfo Enterprise, SevenSteps Professional, and WebWorks Publisher.

Support

Typically, the more expensive the tool, the more expensive the support costs, although this isn't always the case. Be aware that tool vendors can change their support policies! At this time, most vendors implement some of the following support plans:

  • None
  • Free (e-mail only or e-mail and phone)
  • Pay per call
  • Annual
  • Subscription plans that include upgrades

Most tools also have related user groups, where peer-to-peer support is available around the clock. News servers and forums are also available.

One of the most popular user groups is HATT (http://groups.yahoo.com/group/HATT/). With almost 2500 members, this lightly moderated e-mail list provides answers to questions for all tools, although most of the questions relate to RoboHelp.

The following list includes the URLs where you can join the appropriate group.

  • AuthorIT. User group (http://groups.yahoo.com/group/authorit-users/)
  • Deva Tools. User group (http://groups.yahoo.com/group/Helpweavers/)
  • Dreamweaver. Support Center (http://www.macromedia.com/support/dreamweaver/)
  • Doc-To-Help. Help Center (http://www.componentone.com/d2hhelp/index.asp)
  • FAR. E-mail support for registered users. Newsletter (http://groups.yahoo.com/group/HelpwareFAR/)
  • HCW. No support offered by Microsoft. Ask questions at HATT.
  • HDK. User group (http://www.nullarbor.com.au/hdkug/).
  • HHW. No support offered by Microsoft. Ask questions at HATT.
  • The HyperText Studio. (http://groups.yahoo.com/group/hypertextstudio/)
  • Mif2Go. Free e-mail technical support for one year (http://www.omsys.com/dcl/techsup.htm)
  • RoboHelp. Help Community (http://www.helpcommunity.ehelp.com/); HATT; and RoboChat, formerly Parametrica (e-mail only, in the body, type subscribe robochat 'Your email address').
  • Sevensteps. E-mail ().
  • WebWorks Publisher. User group (http://groups.yahoo.com/group/wwp-users/). Forums (http://www.webworks.com/forums).
  • WebWorks Publisher WordHelp. User group (http://groups.yahoo.com/group/wordhelp/). Forums (http://www.webworks.com/forums).

Extras

Some Help developers are looking for additional features in a HAT. For example, if you want to single-source (not repurpose), then you need a tool that supports conditional text.

Multi-authoring support means that more than one developer can access the project at the same time, without having to worry about overwriting someone else's data and without using another tool to help track usage. AuthorIT, The HyperText Studio, and FrameMaker all provide multi-authoring support.

Conditional text lets you mark any amount of text and control which output it is published in. This lets you flag anything from a character to a paragraph and specify if it should be included in the online or printed output. AuthorIT, Doc-To-Help, FrameMaker, The HyperText Studio, WebWorks Publisher, and WebWorks Publisher WordHelp all provide conditional text.

Translation means that you can use the tool to produce your output in multiple languages. You have to design a process that works for you, which typically includes getting the source files or data to a translator and then importing the new information into a new project, but the process depends on the tool.

  • With AuthorIT, your translators can work in the same library to translate the topics. Currently, double-byte languages are not allowed.
  • You can use RoboHelp for single-byte languages, such as French, Spanish, German and Italian, and purchase an Asian Edition for Japanese, Korean, Simplified Chinese, and Traditional Chinese.
  • FrameMaker, Sevensteps, WebWorks Publisher, and WebWorks Publisher WordHelp provide for many languages (single- and double-byte).

Work force proficiency and experience are important if you need to hire someone, either permanently or on a consultancy basis. While there are developers proficient in all tools, typically RoboHelp Office and FrameMaker have the greatest number of experienced users.

Management lets you keep an eye on the project as a whole. AuthorIT and Sevensteps include optional project management modules that you can install. AuthorIT also includes built-in content management functionality, letting you use version control or track the history of any object.

Combining Tools

Back in the mid-90s, developers never used just one tool to create output. They used whatever tool was right for the job. Then, as the tools matured, many developers started to use only one tool. Current tools offer different functionality. By combining tools, you can play to their strengths and use each tool for what it does best. For example, use:

  • AuthorIT for multi-authoring and reusable content with RoboInfo or RoboHelp Enterprise for feature-rich server-based output
  • Any tool with HHW for the latest features from Microsoft
  • Any tool with FAR for added development functionality

Learning Tips

Learning a particular HAT is easier if you already have some basis in the underlying technology. For example, learning Deva Tools will be easier if you already know Dreamweaver. Learning Doc-To-Help and AuthorIT will be easier if you already know how to structure documents and use consistent styles. Learning WebWorks Pubisher will be easier if you know Frame.

Once you learn one tool, you can usually transfer your skills and knowledge to another. However, if you switch from a Word-based tool to a non-Word tool, be sure to focus! Otherwise, you'll try to use Word functionality where it doesn't exist.

Conclusion

Choosing a HAT is not an easy task. Work your way through the list of factors, ruling out those that don't apply. Compare those that remain and you'll soon have a short list of tools to consider. Then you'll be well on your way to selecting the right tool for you.

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 MVP. You can reach her at .

Broadside in PDF | Print-friendly Article

Resources