What Should You Look for in Online Help Authoring Tools?

Better documentation is widely recognized to be better for business, but selecting the optimal documentation tool is often mired in comparison of features, particularly similar features, never knowing for certain whether all have been considered thoroughly, and with the risk of either overpaying for features that never get used or finding that features that appeared to check all of the boxes during evaluation prove to be ineffective in actual use.

Content creation flexibility determines your long-term success

The way a team authors within a particular tool set determines the way that team will work each and every day. If a tool enables a team to author all types of content within one project — step by step instructions, interactive features, and multi media — then that team can author and complete projects much faster than a team that is confined to authoring within a single type of content within a single application.

A good template system is worth far more than all the features listed above, because a good template system will get you started with good content and then allow you to adapt that template to your needs for each topic. The vast majority of the documentation you create will be of a single type (e.g. How To’s) and thus would be created very efficiently using a well-designed template system.

For that reason, for us the way that content is formatted is a lot more important than the way it is written. Of course this then has an impact on how that content is then reviewed as well.

Source format: It is important to store the documentation in a standard format like HTML, XML or even markdown instead of a proprietary format of the vendor to avoid vendor lock-in.

Another important factor to consider is how your authoring tool will integrate with the rest of the work that your team does. For example, will your authoring tool be able to import existing documents written in Word, in Google Docs, or even in HTML or other authoring files? And, how will your authoring tool work with your team’s version control system? Saving a lot of time and avoiding many errors when updating content is possible if you choose online help authoring tools that support your workflow.

Multi-format publishing saves resources

Documentation created with single-sourced content can be easily published in many formats. This can include help in a knowledge base online, printed documentation in PDF format, or even online help viewed from within an application on a mobile device.

Also, pay close attention to how the authoring tool will output the content and how that help will look on the web. Some tools will create very clean and fast help while others can create huge amounts of HTML that causes the help to load slowly and perform poorly in searches. Ask for examples of output from each tool you are evaluating and test them out in a browser on different devices with different connections to get a feel for how they will perform in real-world scenarios.

Collaboration features become necessary at scale

While many documentation systems are used by solo authors, for large amounts of documentation that will be used by many people, the way that your team will work together as authors is critical. Review the workflows for review, the commenting system, and approval process. Authoring roles for writers, subject matter experts and managers should be supported.

Collaboration tools in documentation authoring tools that support real-time documentation editing can greatly reduce problems associated with more than one person modifying a section of a document at a time with one person’s changes being overwritten by the other person’s changes. Cloud-based documentation tools generally have much better support for real-time documentation editing than do desktop-based documentation tools. There are trade-offs between increased functionality in cloud-based documentation tools and decreased control over one’s own content infrastructure that one must consider.

The documentation tool will help to manage changes to your documentation. Tracking changes to documentation, comparing different versions of the documentation and recording who made what changes is a key requirement. This is particularly important for external contributors as well as for organizations that are required to maintain compliance documentation.

Search and navigation architecture

In order to generate a search function for the help that is as useful as possible, the search and navigation architecture of the authoring tool needs to be able to understand the context in which it is entered. Basic keyword matching is not sufficient for complex documentation sets.

Standard keyword search is typically not sufficient to find what a user is looking for when documenting a large product.

As documentation authoring tools make the transition to be used as the basis for your documentation’s search function, the ability to setup search in a way that is relevant to users becomes increasingly important. As documentation sets get very large, simple keyword searching is no longer sufficient to return results that are of value to end users. So, authors should pay close attention to the search architecture of any documentation authoring tool that they evaluate for use as the basis for the search function of your documentation. In addition to the search function, documentation authors must also pay close attention to the architecture of the content’s publication that is generated by the tool, to ensure that the structure of the published documentation’s menu system is set up in a way that is logical for users of your product or service. The menu structure of your help published from your documentation authoring tool is very important and some tools have a very rigid menu structure, while others have a very limited number of ways in which topics can be nested within other topics.

Cross-references and links between the different source documents mean that, for example, instead of duplicating a procedure in several help topics, they can be referenced or included in their entirety in the help topics where they are required. When the procedure changes, it then only needs to be amended once.

Making the evaluation decision

So where do you start? It’s a good idea to start with a content audit, where you make an inventory of all the different types of documentation that you have, how often they are updated, and where they are distributed. Then you can use that list to work through your list of required features of your authoring tool in priority order.

Test the tool with your real content – not with a fake sample project. A tool can look good in a demo or even in a trial period with a sample project, but once you really start to use the tool for your real documentation the problems become apparent. Go through the typical work processes you go through for your help topics and see how the tool handles.

Cost of ownership. The cost of a tool is not only the license fees but also the costs for training, for the needed setup, and for the maintenance. Some tools are more or less equal in features, but are very different in set up, and in needed customizations. Therefore, the total cost of ownership is a very important point to take into account during the evaluation process.

The best documentation authoring tool is one that works in the background. You will only notice the excellent quality of your content and how your end users will benefit from it. Therefore, take your time and thoroughly evaluate the available tools. It is not much fun to change to another tool later on. You will have to set up everything from scratch. In addition to this, you will have to train yourself and your colleagues to work with the new tool. And, of course, you will have to migrate your existing content to the new tool.

People Also Read: What Makes a Professional Workstation GPU Different From a Gaming Card?