How to Choose a Help Authoring Tool
A help authoring tool is a program that you can use to create help files, Web-based help systems, printed manuals, and other kinds of documents.
Modern help authoring software allow the author to write topic content, and to create the Table of Contents (TOC), and Index directly with the built-in editors. However, some help authoring tools can also create help files using an existing document as the source.
Product: HelpSmith 10.1, HelpSmithSetup.exe (65 MB)
Platform: Windows 10/8/7/Vista/XP
A basic feature set of a help authoring tool
Thus, the basic features of a help authoring tool are: supported output help format, the possibility to write content in a full-featured word processor, built-in Table of Content and Index editors, and so on.
In addition, a help authoring tool may include automatic TOC generation, automatic Index generation, spell-checker for different languages. Also, some help tools may provide image editing capabilities, and the possibility for importing and exporting content, for example, for translation purposes.
Selecting a help authoring or documentation tool
Basic features of a help authoring tool
| Features that you may need | Comments |
|---|---|
| Supported help formats | A help authoring tool may support different help formats such as HTML Help (or CHM help), Web Help (or browser-based help system), Adobe PDF, MS Word, ePUB, JavaHelp, etc. So you should determine which help format you need to create before you purchase a help authoring tool. |
| Built-in word processor with a spell checker | Writing content is a biggest part of work on creating a help file and you should also check if your help authoring tool provides a full-featured editor (or word processor) that has a spell checker for the languages you plan to work with. |
| Single sourcing | Many help authoring tools allow you to create a help file in different formats from the same source help project. This means that you can write a help project once and then re-use it, for example, for creating a CHM file, Web Help, and a PDF file. |
| Supported graphic formats | You should check that your help tool allows you to use at least the following graphic formats: Bitmaps, Metafiles, Icons (.ICO), JPEG images, GIF images, and PNG files. |
| Supported video formats | A help authoring tool should include support for the video files such as: AVI, WMV, MPG, Flash animations (SWF), and QuickTime Movies (MOV, MP4). It should also be possible to insert external videos from YouTube and from other video hosting providers. |
| Help system customization | Probably you will need to customize the help file you have created. Some help tools provide a minimal set of possibilities making customization possible. However, other help authoring software include a set of customization capabilities such as the possibility to create and edit templates, the possibility to edit text styles, and so on. |
| Context-sensitive Help | This is a basic feature if you are creating a help file for an application. In this case there are two help formats, HTML Help and Web Help, for which you may want to provide a context-sensitive Help or, in other words, to be able to integrate it with your own application. |
| Table of Contents editor | Most help authoring tools allow you to create and edit a Table of Contents of your help system. Some HATs also provide a feature that may automate TOC generation. The main thing to which you should pay attention is how the TOC handling is implemented in a specific tool, which types of TOC items you can create and how easy is the process of creating a hierarchical structure with chapters and sub-chapters. |
| Index editor | Similarly to the TOC editor, the built-in Index editor should allow you to easily generate an alphabetical keyword Index of your help file. |
| Hyperlinks | You should check which types of hyperlinks you can insert in your help file or printed document. The following are the basic types of hyperlinks that should be supported by a help authoring tool: link to a topic within the same help file or document, an external link to a web page, a hyperlink to an email address. |
| Image file management | A quality help file usually contains a big number of graphic images, so it is important how your help authoring tool manages images. Some help authoring tools simply link to an inserted image file, which make it unreliable when that file has been deleted or when you need to move an entire help project, for example, to another computer. Thus, it is preferable if your help tool provides a centralized control on the images used in your help project. |
| Tables | Ensure that your help authoring tool allows you to insert tables and which options are available for editing table styles such as backgrounds, borders, spacing values, etc. |
Advanced features of a help authoring tool
As to the advanced features, a help authoring tool may include the possibility to create a help file by a team of technical writers, a conditional compilation feature making it possible to generate different version of the same help file, full control on the content's HTML source, translation, and other tools, which are required mainly in the corporate segment.
To help you choose a help authoring tool from the products available on the market, we have prepared a simple table that includes basic and advanced features, which you can review to decide whether a particular HAT suits the needs of your help project.
Advanced features you may need for a help authoring tool
| Features that you may need | Comments |
|---|---|
| Conditional compilation and conditional text | You may need conditional compilation to generate variations of the same help system. The most popular model implemented in help authoring tools is conditional compilation based on so called build tags, which makes it possible for a technical writer to exclude specific help topics, or specific parts of a help topic which is also known as Conditional Text, according to a set of build tags defined at the help file compilation stage. |
| Variables | If your help authoring tool supports variables, it usually means that you can re-define names, insert dates, and custom values directly into the topic content, so that the value can be easily modified without the need to review the entire help file. |
| Templates | Templates usually allow you to customize the view of the help file you are creating. Some help authoring tools support templates for the entire help file, and other HATs make it possible to customize the view of individual help topics. |
| Text Styles | Similarly to templates, the support for text styles allows a help writer to easily change the appearance of an entire help file by modifying font attributes such as font name, size, color, which are used in the help project. |
| Command line compilation | If you are creating a help file for an application and prefer to automate the creation of your software build, make sure that the help authoring tool you are planning to use also allows you to compile your help file from the command line. |
| HTML code control | If you want to edit the topic's HTML source directly or simply to be able to insert your own HTML code into the content, you should also check if your help authoring tool allows you to do this. |
| The capability to handle large help projects | A help authoring tool should be able to work with large help projects and it is important to know that different tests and reviews show that many free or low-cost help authoring products available on the market are not optimized for creating a serious help file with large amount of content that may include images and videos. |
| Project analysis and reports | Some help authoring software provides reports such as statistical information, information on broken images, and so on, which may be important on large help projects, for example. |
| Localization and translation | If you plan to translate your help file into other languages, check which possibilities your help authoring tool provides for this task. Some HATs include an import/export capability for external translation while other help tools make it possible to work on a translation directly on the same or on a copy of the original help project file. |
| Team work | This feature is important for a team who need to work on creation of a help file or printed manual by multiple persons. So if you are choosing a help authoring tool that will be used for collaborative working, ensure it includes such a capability. |
Conditional Compilation in a Help Authoring Tool
Conditional compilation is one of the features making a help authoring tool different from a regular word processor or a simple help file compiler program. If your help authoring tool supports this capability, it means that you can easily get different versions of the original help file (or document), so that the resulting help file can contain a different set of help topics or even different content in the same topic.
In a help authoring tool, conditional compilation is usually based on build tags that you can setup in your help project and then select before you generate the final document or help file. Thus, using build tags, you can create a help file for a specific case, for example, such as a help file for a particular version or edition of your application, or a help file created for your marketing or distribution partner, so the help file's content may include the partner's contact details, website URL, logos, etc.
Download a Help Authoring Tool
If you a looking for a suitable tool to create your help file, you can view the Choosing a Help Authoring Tool section for the list of features that you may need to complete a particular project.
Also you can download one of the recommendable help authoring tools which includes support for multiple help formats, an easy-to-use UI, and advanced features such as conditional text.
| Details | Value |
|---|---|
| Filename | HelpSmithSetup.exe |
| File size | 65 MB |
| Platform | Windows 10/8/7/Vista/XP |
| System requirements |
1 GHz processor, 512MB RAM, 150MB free disk space |