How to Select a Help Authoring Tool for Your Project
If you are looking for a help authoring tool to create a help file, online help system, or printable documentation, you may be asking a question what your documentation tool should be able to do, or which one from the help tools available on the market to select for a specific project? Should you purchase versatile and expensive documentation software which are mainly oriented to full-time technical authors, or there is an affordable tool that you can use to successfully complete your project and save your budged?
Since help authoring tools are constantly improved by their vendors, it is hard to recommend a specific application for any project. Despite, we have prepared a list of features that you can use as a check-list before you start a new documentation project. In other words, you can plan what tasks you need to solve while working on a help file or manual, and also what feature your help authoring tool should provide to make that possible.
Finally, you can find our quick overview of the major help authoring tools available on the market and make your choice.
Help File Formats
What help file formats do you need to produce? Most popular formats for help files are HTML Help (.CHM files), browser-based online help (or Web Help), Help 2.x, and JavaHelp. Most modern help authoring tools provide single sourcing, which means that you can produce documentation in various output formats from the same source help project.
Printable Documentation Formats
If you also need to create a printable version of your documentation (for example, a printed manual), ensure your help authoring tool provides the possibility to create MS Word files, and Adobe PDF documents. Also, you should check that the printable documents include working hyperlinks to topics within the document, external hyperlinks to a web page or email address, images, tables, and other objects that you may need.
Build Tags
Build Tags (also known as conditional compilation) allows you to produce documentation oriented to different audiences of users from the same source project. Some help authoring tools support only limited conditional compilation capabilities, while the other tools make it possible to produce different versions of the Table of Contents, and also different version of content from a specific topic. Also, you may want to be able to add custom build tags and have the possibility to combine different build tags for a specific version of your help file or manual.
Content Writing
Does your help authoring tool provide a full-featured word processor, or it uses on a third party editor? Since writing documentation is the biggest part of work on any documentation project, ensure that your help tool provides comfortable working with text, the possibility to customize font and alignment settings, to create and re-use styles, and that it also allows you to add Images, embedded and hosted video clips (for example, from YouTube), tables, hyperlinks, lines, and other objects that you may need in your manual.
Dynamic Styles
When writing content you may want to be able not just to use different fonts and paragraph formatting settings, but also have the possibility to change the formatting of the entire help file or manual at any time, or to generate a help file or PDF documentation (as well as other output formats) with different font and formatting settings. To provide this possibility, the word processor in your help authoring tool can support dynamic styles, or even have support for CSS style sheets, which means that you can modify a style and provide alternative formatting settings for use in other outputs without the need to manually change a large amount of content.
Spell Checker
When writing content it is important to avoid spelling errors, so ensure that your help authoring tool includes a spell checker and provides dictionaries for the languages that you plan to use.
Control Over Source Code
Some help authoring tools provide full control over the HTML code of the content being written, so you can write and modify the HTML structure according with your needs. At the same time, the other tools generate the HTML code automatically, so you can simply concentrate on writing text in visual editor without the necessity to deal with coding HTML/CSS. Thus, the need to control over the underlaying HTML code depends on a particular help project and specific tasks.
Multi-Media Features
Obviously, to develop a quality help file or manual, it is not enough to just write content with instructions explaining how to perform a task or solve an issue. Your help file will be more useful if you prepare and add images and videos that will illustrate the subject being documented. From the technical point ensure that your help authoring tool allows you to insert images in most popular formats such as BMP, JPG, PNG, GIF, and video files such as AVI, WMV, MPG, Flash (SWF), and QuickTime (MOV, MP4). Also, ensure that it is possible to insert videos from YouTube, Vimeo, and other popular video hosting services.
Built-in Screenshot Tool
If you are working on a help file for a software application or web service, you will also want to provide screenshots. Of course, you can use a third party utility or full-featured graphic editor like GIMP to prepare the screenshots. However, some help authoring tools provide an integrated screenshot tool that simplifies the process of creating a screenshot and inserting it into your help file.
Working with Tables
Tables are also an important part of content, for example, when you need to display some details in a presentable and comprehensive way. Of course, being a basic objects like images or hyperlinks, tables are supported by most of the help authoring tools, however, the table-related features may differ - for example, customization possibilities for borders, the possibility to apply CSS classes and styles to individual elements of a table, the possibility to re-use the appearance of one table for another table, ready-to-use design templates to apply to a table, and so on.
Hyperlinks
Usually, a help file or printed documentation includes hyperlinks to other topics within the same manual, hyperlinks to related web sites. Also, you may need to use hyperlinks to anchors (also known as bookmarks in some help file creation software), for example, to create a glossary of terms or provide a FAQ section.
Layout Customization
When it comes to customization of the design of your help file or manual to fit it to the common style adopted in your company as part of the brand identity strategy, or simply when you want to provide a common style of your online help system with the product's website, it is important which ways your help authoring tool enables you to accomplish that task. For example, a help tool may suggest ready-to-use design themes for the Web Help layout, the possibility to create a custom theme by means of the help tool, or by modifying the HTML/CSS code of the help system's layout.
Help File Integration
Integrating a help file or browser-based Web Help system with your desktop application or web-based service usually implies that the end-user can get assistance from a particular part within the application. For example, the user can simply press F1, so the application will automatically display the corresponding help topic. Or, the application can show assistance information like hints in the application directly.
It should be pointed out that if you create an HTML Help (CHM) file for a desktop application, integration is mainly based on HTML Help API or on the built-in support for CHM files of your IDE. However, for an online help system, it mainly depends on the possibilities provided by the developer of the help authoring tool: for example, a Web Help system can simply allow you to open a specific help topic (which is enough in most cases), but also it can provide API, so your application can retrieve information from the help system, or to integrate the Search feature, and so on.
Table of Contents Tool
The basic task of the TOC tool in any help authoring software is to let you build the structure of your help file by adding and organizing headings, sub-headings, topics, external links, and so on. In some cases, you may also need to provide different versions of the TOC, say, for a help file and for printed manual. Some help authoring tools implement that facility making it possible to keep different TOCs, the other tools allows you to compile different version of the same TOC relying on their Build Tags/Conditional compilation capabilities.
Keyword Tool
Similarly to the TOC, keyword Index is a standard navigation tool that present in many help file formats. While most help authoring tools allow you to build a keyword Index, some tools also make it possible to generate it automatically by analyzing of keywords which present in your documentation.
Content Re-use
Your help file may include repetitive parts of content including single lines of text like names or product version, or an entire guide such as instructions explaining how to perform a task. Therefore, some help authoring tools implement the functionality of snippets that you can write once and re-use in other places of the documentation.
Design Themes
Templates is usually a tool that enables you to change the common style of help topics, or the appearance of the entire help system (for example, for the Web Help layout), or the common appearance of the printable manual. Thus, a help authoring tool may include built-in features allowing you to customize design settings for topics, or for the help system's layout, provide you with the possibility to select a pre-built design theme, and also provide the possibility to create a custom design theme.
Variables
Variables in a help file tool are placeholders for reusable content such as names, product versions or dates that you can insert into multiple places of your help file, however, save the possibility to change/update their values at any time without the necessity to revise the content of the entire help system.
Automation
If your help authoring tool includes support for the command line, it may allow you to automate some frequent actions such as compilation of the help project into a particular output format with a specific set of build tags, etc. This, in turn, enables the developers to automate creation of software builds, compilation of custom versions, and other similar tasks.
System Resources
Whether you are going to create a small-sized help file, or to build a large help system with a big number of topics, images, and videos, it is crucial for your help authoring tool to be able to handle such a help project. You may want to check the system requirements from the developer of a specific help tool, as well as to test it with a sample help project containing the corresponding amount of help topics, content, and images.
Translation Capabilities
If you plan to provide a help file for your product in more than one language, check what solutions for this task your help authoring tool provides. Some help file tools imply that you will translate a copy of the original help project, the other tools make it possible to translate content in the help project directly (including content of help topics, titles for TOC elements, keyword Index, and project settings such as titles, etc.), or to export the help project for external translation (for example, to an XML file or MS Word document).
All of these methods have advantages and disadvantages: for example, the translator may need an additional license for a help authoring tool, or they may not modify the same help project since it is maintained by another person, or you will face the problem of updating a translated project with new data from the original project.
Team Work
In case of working on a large help system, you may need to divide the work between several technical writers, so each person will develop and maintain a specific part of the entire help project. While some help authoring tools include basic capabilities for team work allowing you to import/update content created by other persons, the other tools allow you to merge content from other team members by means of a version control system such as Subversion (SVN).
Comments