What features matter most in online help authoring tools?

I have a great technical writer at my previous workplace. It takes her 40 minutes to update a warning message. That warning message is always the same. The same 40 minutes of her life every time she updates that same warning message. But that warning message is in 12 places. 12 topics in 12 documents of help. It’s a pity. She would love to do a better job if only she had a better tool for technical writing. I know of no one who enjoys being restrained by the limitations of a tool more than a technical writer.

In our comparison of help authoring tools for technical writers, we differentiate between two questions. First, what features will save your documentation team from tedious work and grueling work? And second, which features does a tool for technical authors offer to document content.

The single-source problem nobody talks about honestly

Outgrowing a process before you realize it’s outgrown is a documentation process problem. One writer becomes three, three writers become a department of technical writers, and all that content is scattered across multiple files in multiple tools (e.g., Word docs, a wiki, PDFs, a help portal set up by a contractor a few years ago that nobody fully understands). Then you have to manage a sprawl of content. Documentation processes are usually put in place to support the work of a single technical writer. Managing a process that supports a group of technical writers is significantly more complex. Managing a process that supports a department of technical writers is even more complex. Managing a sprawl of content is incredibly complex.

The next level of documentation sprawl is just plain bad. The worst part of dealing with a lot of documentation is that the documentation can be spread across a variety of tools. That means there is a great deal of potential for inconsistencies and inaccuracies, no matter how hard you try to keep everything straight. And then there are the simple tedium of having to make changes in multiple places. I am referring to things like changing a warning label on API documentation. The same warning label appears in a number of different documents. You make the change in one place and then have to check to make sure that the same change has been made in all of the other documents where that warning label appears. FAQs, Help pages, and other supporting resources for the documentation can also need to be updated.

Write Once, Publish Many. First and foremost, the online help authoring tool should support single-source publishing (SSPSS). Write one document and it automatically and instantly republishes to PDF, web help, to mobile and so on as required by your customers. The other features (collaboration, search, themes) are important, but much less important than PSS. So stop evaluating an authoring tool immediately if it doesn’t support single-source publishing.

What actually matters when you dig into the feature list

Documentation authoring tools offer a long list of features, many of which you can use to tailor your working with your documentation as you like. The list of these features is indeed impressive, however, most of them are rather paralyzing. In the following I want to restrict myself to a much shorter list, which actually is relevant and helpful for your daily work as a technical writer.

The features that consistently make or break a team’s daily workflow:

• Conditional content: the ability to show or hide content based on audience, product version, or output type, without maintaining separate files for each variation
• Variables and snippets: reusable chunks of text (product names, version numbers, legal disclaimers) that update everywhere the instant you change the source
• Search and findability controls: the ability to weight search results, exclude certain topics, and give readers actually useful outputs instead of a wall of marginally relevant links
• Reliable output to multiple formats without manual reformatting every single time

Many authors would say that absence of features like a built-in grammar checker, fancy theme templates or even an AI-powered suggestion engine that offers to rephrase a sentence in the best possible way to use alternative synonyms, are nice to have features but are not features that you will thank your stars for when things are getting really tough on you at 4 pm on a Friday evening, and all that’s standing between you and a published update is your tool behaving itself as you make your final changes to a document.

Collaboration: the underrated dealbreaker

As a counterpoint, the features of your documentation tool that DO NOT SUPPORT YOUR WORKFLOW can destroy a writer’s life very quickly. More on this below.

Collaboration within Technical Writing teams, and between Technical Writing and other departments and teams, is becoming more common. As a result, there are many situations where a writer works with Subject Matter Experts (SMEs), with people in Localization, with Program Managers, and with many others. Indeed, some writers even work with programmers who can generate API documentation, and this API documentation must then be incorporated into the rest of the documentation set for that product. Most tools that writers use today are at odds with the processes of the writers who use these tools. So for example, a writer might make use of a number of features of a given tool in order to complete a single piece of content. When that content is reviewed by others, as it inevitably will be, they will have to read through all of the files in which that content appeared, for example all of the .doc files, or all of the .html files, rather than being able to review the one piece of content that the writer had created using the tool. This is a huge source of inefficiency for writers, and the number one reason that they are dissatisfied with their tools.

For teams of writers working in topics as review workflows that are entirely within the publisher are very important. The worst feeling in the world is working with a topic in collaboration with another writer, and then finding out that both of you have edited the topic and that neither of you knows which is the current version. That’s a very bad afternoon.

Team type	Top priority feature	Common pain point without it
Technical writing teams	Single-source publishing	Duplicate updates, version drift
Localization teams	Translation workflow integration	Manual handoffs, inconsistent terminology
Learning and development	Output format flexibility (SCORM, PDF, web)	Rebuilding the same content for each platform
Small documentation teams	Templates and content reuse	Starting from scratch every time

Learnability

Learnability: This feature is very important for you to know as soon as possible how long it will take for new technical writers to start publishing their own work after being introduced to your technical publishing tool. Ideally, this should be as quick as possible, so they can start right away to begin producing their own content for customers.

While the powerful documentation and help authoring tools available today have very high capability ceilings, there are also very high entry costs for many of them. I’ve seen organizations spend a lot of money on very expensive onboarding processes that quietly demote very capable technical writers to mere authors of low quality, published content until they leave the organization. Many of these tools are opaque to their writers and publish high quality content at great expense of time and pain. In order to become fully effective with a documentation or help authoring tool, a technical writer must learn to use the tool in addition to mastering the subject matter of the documentation or help being written. Therefore, organizations must be very careful in how they bring new writers on board and assess the true technical comfort level of potential writers before investing too much time and money in onboarding them to a tool and process. In order to get the best return on the investment that an organization is making in documentation tools, the onboarding process must bring the writer’s full potential and not silently and gradually diminish it.

If possible, set up a trial version of the application and complete a real project using the tool. Then determine how long it takes a person with absolutely no prior knowledge of the application to become proficient enough to start publishing content. The number of hours lost by your team will likely equal the amount of time and money spent by your team to complete the evaluation of the application.

Choosing the right technology is only part of improving organizational efficiency, and Auraa Business regularly covers practical business strategies, workplace innovation, and digital transformation ideas that help companies make better long-term decisions. 

(And yes, I am returning to that opening story of a technical writer losing 40 minutes of time because of a workflow. The writer in that case knew her content backwards and forwards. The problem was that the tool was opaque to her, and the cost of that opaqueness compounds.)

So, what should you actually look for?

1. Single-source publishing that works across your required output formats
2. Robust content reuse (variables, snippets, conditional text)
3. Collaboration and review features that fit how your team actually works
4. A learning curve your team can realistically handle

There is no perfect documentation tool – at the end of the day, it’s still documentation, and there are things that are naturally easier than others. However, your documentation tool should make the ‘easy’ things easy, and the evaluations for the various documentation tools are worth taking the time to complete.