Evaluating tech writing software

Here were the criteria a publishing system had to meet for my project. Criteria for your project will be different!

  • HTML as primary output
    • Although PDF was a request, it would not be a priority.
    • Pages should also display reasonably well on small-screen devices.
  • Relatively easy to use: Technically minded colleagues would be able to update (and translate) pages with a minimum of training.
  • Usable company wide: Developers could use the tool to create content.
  • Localization: Publish in many languages (particularly Chinese). Could also export files that were translator-friendly.
  • Support single sign-on: Currently in our products, pages are only visible to signed-in users.
  • Multiple branch support: Writers and developers could work in a release branch, to be later merged into the main branch for feature releases.
  • Extensible: The platform lets you add extensions and libraries to extend the site’s features.

I was already familiar with page creation using Markdown. Additionally, I knew that content reuse would be a low priority, as I was documenting several different products of moderate complexity.

What are the choices?

Component content management systems

These used to CMSes, but they gained another ‘c’ along the way and became CCMSes. The ‘component’ part signifies you can stick little pieces together to build many output variants.

These products are often (but not always) desktop clients. They’re generally well documented and their licenses include support. They additionally offer several output formats and are particularly strong on content reuse. The ones I’ve come across most often are Madcap Flare and Paligo. Some others are AuthorIT, RoboHelp and Framemaker.

Based mostly on comments in r/technicalwriting on Reddit, people seem more content with Flare than Paligo. Also the nicest web output I’ve seen has been generated by Flare.

Again, as I didn’t really need advanced content reuse, I didn’t consider any of these. Also, they’re only available to tech writing teams.

Additionally, their licensing costs are often eye-watering. And on top of annual user licenses, they often charge for ‘reviewer licenses’ to boot.

XML-based formats

These are similar in many ways to CCMSes and tend to be XML-based.

The most well-known is DITA; another is DocBook.

These setups are really for large teams of writers, particularly in hardware, where content reuse and consistency trumps everything. They tend also to be expensive and you have to pay someone to set them up. What I’ve seen of their web output also seems to be pretty damn ugly.

Again, it wasn’t the tool I needed and they aren’t widely used to document software.

Help-authoring tools

There are several of these: Document360, ClickHelp, Dr Explain and Helpjuice to name a few. They’re usually cloud-based and their pricing structure is less extortionate than some of the CCMSes I listed.

If you have better things to do than edit configuration files, CSS and HTML, then I really don’t begrudge you paying for one of these. But I still wanted something more open and configurable.

Headless CMSes

This is a more recent development. To put it simply, you write your content to a database, then you build your output using API calls. This gives you tremendous flexibility, plus the opportunity to populate multiple formats with content—even smartwatches and smart speakers.

I’m not yet aware of an out-of-the-box setup that’s specifically geared for tech writing, but it’s an interesting category nonetheless.

Static-site generators.

It’s no secret than I chose one of these. I’ve written more about this topic here.

Static-site generators basically take plain text files and convert them into nice HTML pages, without the bother of a database. Many, but not all, utilize the Markdown format.