This guide will cover everything you need to know about help authoring tools for your business. We provide definitions, use cases and features you would expect from these tools. We then compare some of the most popular help authoring tools, to help you understand what’s right for you.
25 min read
Help Authoring Tools are popular software solutions in the enterprise. They typically fall under the category of development software, since they are typically used to author software documentation or document other technological products.
In reality, HATs can be used in almost any industry where producing robust documentation is essential. They are content development tools that help you produce documentation for a wide variety of platforms, and manage large volumes of content aimed at different audiences.
With many Help Authoring Tools, specialist training is required. In other cases, they are usable right out of the box.
“Help authoring tools are programs designed to assist technical writers in designing, publishing, and maintaining software help documentation. The resulting text is used in explanation guides, manuals, and help files.” G2 Crowd
There is a wide variety of Help Authoring Tools on the market. Help Authoring Tools generally facilitate a content creation process, and are intended to be used by specialist technical writers. To qualify as a Help Authoring Tool, software must:
You’re actually somewhat treating your text content like code. HATs are typically used by enterprise companies managing large amounts of legacy documentation, as well as looking to publish their documentation across many channels in different formats.
Help Authoring Tool help you single source your content. This means that content creation is centralised and source files are kept in a database – a single source.
During the build process, your content is then output to different formats which can range from ebooks to PDFs, printed manuals to HTML websites, CHM files to contextual help – all from this central source. The list of possible documentation outputs is fairly endless. Often your choice of HAT hinges on which outputs it supports.
As we’ve already mentioned, there are some distinct features that distinguish a HAT from other types of software.
Here’s a quick list of features you might expect:
We’ll now go into a bit more detail about what these features look like in practice.
When you purchase a HAT, you will download your software solution to your desktop and authenticate your account. Upon logging in, you will have access to the dashboard where you will see what amounts to a Content Management System. You have the ability to start creating documentation source files, as well as the ability to import existing documentation in a variety of formats.
The creation and management of these source files is kept separate from the actual formatting and output of the final versions(s). This makes updating your documentation much easier as you can make use of topics, snippets and variables to apply global changes. Topic-based authoring means using individual text files for each topic that can be swapped and reordered.
You also may not require the full set of documentation in one of your outputs for example. You may want to create a printed booklet that contains just some of your topics, but then also generate a help center website containing the full range of topics. You can do both these things from your Help Authoring Tool.
In service of these goals, Help Authoring Tool containing content publishing capabilities: WYSIWYG editor, code view, CSS/HTML/JS formatting capabilities, and more.
Help Authoring Tool have a number of benefits for your business. Mainly, they help you produce a large amount of documentation and also manage your existing documentation.
Updates can be made easily and quickly in multiple places in your documentation using tools like the topics, snippets, or variables. Some tools also allow you to display conditional content to different users, so you can personalise the help experience. Multiple technical writers and Subject Matter Experts can collaborate on the same projects, and you can keep track of the different versions.
Help Authoring Tool save you time so you can do more work with fewer people. HAT manage your source files centrally in a database so the content is decoupled from the presentation. In theory that means you can write once, instruct the system in how to present your content, and publish your documentation with the click of a button.
When you provide thorough and helpful documentation for your users, this can help you reduce support costs. Self-service support is cheaper than employing many support agents to manually answer the same questions. And customers now expect a self-service portal.
There are many types of documentation for which companies might be seeking Help Authoring Tools to help them build. You might need to create:
Often, companies need to create a range of documentation types, but using roughly the same content for each type.
The common thread is that you are usually producing web and print based content intended to help the users of your product or service, or your internal employees. Your company may be legally required to produce documentation that is up-to-date and accurate regarding its products and services.
For example, you could be documenting some kind of proprietary, in-house computer program for call center and business office employees. Alternatively, you could be documenting a range of user guides, installation guides, conceptual guides and quickstart guides for fiber optic technologies. You might be producing a help center for a hotel booking system. You could be creating an employee handbook, a student elearning center, or producing compliance policy regulations for your research laboratory.
In each of these theoretical cases, you might have a variety of mediums on which you want to publish your documentation. You need the ability to for teams of technical writers to collaborate on your source files, and automatically generate the published versions. You want to not only write and format your content, but also be able to instruct the system on how to generate output.
You must be able to update your published content at any time (including potentially far in the future), and easily update multiple instances of the same content without manually re-typing (or copy-pasting) your new content each time. It may be necessary to translate your documentation into different languages, and also continually update your localised content.
There are other tools that offer some of the functionality that Help Authoring Tool offer, or that perform an analogous function. For example, Static Site Generators also help you create documentation, but their features are more limited.
Once you’ve decided you need a Help Authoring Tool, there are a huge variety of options to choose from. We’ve listed some of the four popular HAT tools below,
If you want to explore more tools in detail, you can check out our article on Best Help Authoring Software & Tools.
Some companies want to know the difference between knowledge base software and Help Authoring Tool. A knowledge base solution is like a more specialised version of a HAT.
Knowledge base software helps you create an online knowledge base for your customers or employees, and provides a user-friendly content publishing process. Knowledge base software may be used by people other than specialist technical writers – such as your developers, information designers, or customer support agents.
In contrast, HATs are geared towards multiple platforms and formats, and provide a system for single source publishing. Your documentation is managed within your database, and has been decoupled from the final output formats. The focus is usually on writing documentation in an XML or similar format, and manipulating it for use across desktop, web, mobile, and print.
Knowledge base software means that the same person or team can manage the content production, and end user support. Account holders can write, edit, and publish content, view how that content is performing in the back end, and manage user feedback. The knowledge base is often hosted alongside your main brand website, or linked contextually within your software product.
Why go with a paid proprietary solution, you might ask, when there are so many free software solutions out there.
It’s tempting to go with a free Help Authoring Tool, especially in the first instance when you’re not sure if a tool will suit you. Lowering costs is also not a bad idea for any business – but it’s equally true that there’s no such thing as a free lunch.
First off the bat, free isn’t the answer for Help Authoring Tools. Ask yourself why this product is free in the first place. It’s usually because you have some kind of limited functionality, it’s open source and needs to be self-hosted, or it’s a free pricing tier and you’ll ultimately need to upgrade.
Sometimes free solutions can be a good choice if you want to integrate your software into a development workflow, and this is where Static Site Generators come into their own. Many of these tools are also open source, and you can benefit from an active user base and community support. Free Help Authoring Tools like OpenKM or PHPMyFAQ are popular for building knowledge bases.
If your organisation operates on open source principles, you should choose the tooling that matches your values. In contrast, if you want to test out a product first without committing to payment, opt for a solution like Document360. It’s available on a free trial so you can find out if it suits your needs.
As we’ve just mentioned, open source Help Authoring Tools are a popular solution considered by companies producing documentation. These tools include Sandcastle or Mediawiki, and they come with a lot of benefits and drawbacks.
Open source Help Authoring Tools mean you can access the software source code, and usually customise your solution to meet your needs. You can do what you like – within the terms of your software license. You can also host your documentation in the same place as your product source code, which may be important for your organisation’s security compliance procedures. You are supporting the open source software industry, which promotes making software accessible for everyone.
At the same time, there will be a slower time to market with open source Help Authoring Tools. You’ll require in-house development resources to run and maintain these solutions. You don’t benefit from dedicated software support, and if the open source community behind your solution dissolves, then your product will no longer be maintained.
Proprietary SaaS solutions like Document360 can take a lot of the headache out of the documentation process.
Static Site Generators are an alternative to Help Authoring Tools because their user experience is catered towards software developers. SSGs are seen as a subset of the Help Authoring Tool, specialised for developers and technical writers. They are generally free, but you download the source code and install it on your system.
They were actually developed so that developers could benefit from a better blogging experience. There are now specialist SSGs like Hugo, Jekyll, and Sphinx, that have been designed for authors producing documentation.
SSGs are very technically very secure because no calls are made to your server or database while a user is on a page. Unlike a regular website, your content is not dynamically generated. All content is loaded from the server when the user first requests the page, and there are no interactive elements included in a basic SSG.
An SSG is a good choice if you have the time and resources to devote to developing your site. It’s suitable if having your site live alongside your software product codebase is important you. It allows you to create documentation locally, and preview changes as you write.