Choosing a Help Authoring Tool

Checklist of key criteria for selecting a so-called help authoring tool (HAT). Help authoring tools can be used for creating online help files and user manuals from the same source (single source publishing principle).

Help authoring tools (HATs) are specialized editors and converters you an use to create online technical documentation. Today, many help authoring tools also provide features for single source publishing, which means that you can generate several output formats and versions from one shared text source. While most tools manage to produce different online formats such as browser-based help and compiled help very well, only a few tools can also produce printed user manuals (or PDFs) of professional quality. Big differences also exist among HATs when it comes to translating projects into foreign languages.

Note: You can find a list of tools under Help Authoring Tools.

The primary differentiating characteristic is the question of where and how writers put together their texts and format them.

 

Tools with a built-in editor
The majority of help authoring tools have their own fully integrated WYSIWYG editor.

Advantages: Texts and meta-information can be created and managed together. There are no additional license costs for an external editor. Only one software package has to be installed and updated.

Disadvantage: The integrated editors don’t often provide the same comfort and efficiency as the major text processors. If you want to use macros or auto text, for example, you’ll often have to use a third-party utility.

 

Tools that use an external editor

Other tools follow the contrary approach and use an external editor to create the texts—mostly Microsoft Word, but also, to an increasing extent, FrameMaker, HTML editors, and XML editors.

Advantage: You can use all the functions of your favorite editor.

Disadvantages: Often, operation is inefficient. Because the source data is mostly loaded with additional meta-information (for example, in the form of hidden texts or with the help of field functions), the translation process becomes particularly error-prone. Add to this the typical, well-known problems of the various editors, which means that those who are always reluctant to work with one of these editors, such as Microsoft Word, will never be happy with a tool that integrates this editor.

 

Mere converters

In this group, text creation and help generation are largely decoupled. Complete user manuals (mostly written with Microsoft Word or FrameMaker) are converted into online help only in the second step. The basis for formatting is usually a specific template, which must be strictly adhered to while writing the texts. Moreover, similar to the tools that use an external editor, some additional meta-information often has to be incorporated in the text.

Advantage: This procedure promotes efficient single source publishing, especially if the material already exists in the form of printable user manuals.

Disadvantages: The book metaphor can mislead the author easily into writing contents that are not as modular as required for online help. The results are often mere books on screen instead of media-adapted online help. Another disadvantage is the fact that the documentation for different product versions can’t really be generated from the same source.

Other converters are based on XML-DITA. Using these converters avoids the disadvantages listed above, as it forces the author to develop a modular, online-ready structure right from the beginning.

If online help needs to be Unicode-compatible for certain languages, this restricts the choice of tools. Not all programs support Unicode. There are also significant differences in the translation workflow. Many tools completely ignore translation requirements. Others provide sophisticated export and import options for texts that are to be sent out to external translators, or enable the author to edit several languages in parallel.

Only a few of the classical help authoring tools explicitly support simultaneous editing by several authors. In some cases, this can also be achieved manually to a certain extent at the file level, but this only works for the tools that save each topic into an individual file. If your team is working at different locations, remote access might be required.

Other considerations are:

Does the tool have a built-in version control system or can it be connected to an external VCS?
Does the tool provide any support for the review process?
Does the tool provide a possibility for subject matter experts to contribute information in an efficient and easy way?

The majority of tools claim to support single source publishing, which means creating texts once and then publishing them in different formats and media. As long as these texts are just different help formats, such as compiled help or browser-based help, this usually works smoothly. However, when it comes to generating printable user manuals or PDFs, in addition, the following aspects are what separates the wheat from the chaff:

Is it possible to fine-tune the formatting of the exported documents? Many tools, for instance, don’t export the names of paragraph and character styles. Thus, it becomes barely feasible to achieve a professional print layout efficiently.
Is it possible to automatically eliminate or insert media-typical text fragments, such as “on page” or “in chapter”?
Can the export be restricted to specific contents?

If documentation, both for different media and for different product versions, has to be generated from the same source (such as for a standard version and a pro version) single source publishing acquires one more dimension. Some tools enable you to define so-called conditional texts or build flags to hide specific sections of the text, as required. Other important features are variables and text snippets (sometimes also called embedded topics), which enable you to use individual text sections many times over, such as product names or a warning.

Can the production of documentation for multiple product versions be automated? Is it possible to invoke the tool from the command line or from scripts? Can the tool be invoked along with all the settings and parameters that are required?

Can the tool be integrated into an overall build process?

Some tools are specialized for code, assembly, and component documentation. They scan the source code and automatically generate a completely linked basic framework for the documentation. Citations from the source code are also formatted automatically (the syntax highlighting feature).

Using a low-cost tool can prove to be a costly exercise when a project grows larger than initially expected, or when it has to be revised later on. Most low-cost tools don’t support definable paragraph and character styles and format each word manually. When a global change to the layout becomes necessary, then comes the rude awakening.

A low-cost solution might be an economical alternative only for those who just need to create a small online help file occasionally and don’t have to maintain and update it regularly.

Although all current help formats are backed by the source format HTML, only a few tools give you full control over the generated HTML, JavaScript, and CSS code. Here you’ll have to make a fundamental decision: Do you want to be able to tweak the code manually, or are you looking for a tool that spares you from dealing with most of the technical details?

Finally, there are some questions regarding performance, efficiency, and the scope of functions:

Is there support for advanced navigation features such as expandable sections, a breadcrumb trail, related-topic links, and mini TOCs?
Is it possible to call browser-based help in a context-sensitive way? Or will only the home page (index.html) appear?
How easy is it to import legacy data from other tools?
What other useful functions does the software provide? For instance, some tools come with useful utilities, such as a screen capture tool or tools for image processing.

Apart from the help authoring tool’s set of features, and its performance and usability, you should also take into account the following worst-case scenarios:

What happens if the manufacturer of the tool discontinues the product or ceases operations? Does your tool require a server run by the manufacturer? Does your tool require activation when installed on a new computer? If any of these scenarios occur, could you continue to use the tool for at least a limited amount of time?
How easily can you migrate your source files when you have to (or want to) switch to another tool in the future? Does the tool use open formats such as XML / DITA to store its data? Can you only migrate some output, or can you migrate your project’s source files along with all the metadata?

Did you benefit from this guide? Please help to keep it free also in the future. Buy a copy of the PDF version (approx. 140 pages).

Thank you!

This page was last updated 10/2014.

 

Imprint | Privacy | Terms of Use | Copyright | Linking to Us | Acknowledgements