How should teams compare technical documentation platforms?

I recently got asked to write up a comparison guide for documentation tools. I began to start writing it up, and realized that I don’t really know where to start. The guy asking me for the guide started looking for documentation tools 3 weeks ago. He and his team had started to compare spreadsheets for documenting different things, looked at a few demos, tried out a couple of free trials in a slack channel (where the conversation ended up being a 40+ message long thread), and landed on a tool 3 weeks ago. Now, 6 months later, they’re wondering if they made the right choice.

This is the norm for documentation tool evaluation. People can make decisions. There are lots of “feature comparison” guides to documentation tools, which compare the features and pricing of various documentation tools. Unfortunately, how a writing team works and the flow of work of a writing team cannot be easily translated to a feature comparison guide. Such a guide can be very high level and thus of little use when actually evaluating various documentation tools that your team might use.

So let’s try a different angle.

Start with how your writers actually work

Before you start looking for documentation platforms to test out, you should first get a good idea of how your writers work. Writers who work in structured authoring, in XML, in DITA, and so on will likely need documentation platforms that support their workflows. Writers who work in Google Docs, in Word, and so on may need platforms that are easier to use, or that support markdown, for example. The ability of your writers to work with a documentation platform is likely to be a single variable that eliminates more platforms from consideration than any feature of the platforms themselves.

Some documentation platforms are geared to technical authors that are structured authors at heart – authors that typically work in topic-based fashion, and want to leverage as much reuse as possible from their content. These platforms of course typically support DITA (Document Type Definition) or XML in order to ensure that the greatest amount of reuse can be had from the content authored within the tool. Other documentation platforms on the other hand are geared towards teams of writers who do not necessarily have a structured authoring background, yet need to work in a higher productivity environment without sacrificing content quality or collaboration. Many platforms attempt to support the very structured author as well as the more free-form writer, however I have found that most platforms typically support one type of author far better than the other. This of course can lead to much regret if the wrong tool is chosen for the needs of a writing team prior to ever beginning to use the authoring of content.

Here are a few things to ask yourself before jumping into a long list of potential documentation tools that your writers might find to be useful to them. Map these out and you will have

• How many people will be authoring content regularly, versus just reviewing it?
• Do you need to publish to multiple outputs (PDF, web, in-app help) or just one?
• Is version control a hard requirement, or a nice-to-have?
• How much does your content change with each product release?

These questions don’t have a right answer for everyone. They have your answer.

The publishing workflow question nobody asks early enough

Managing the documentation’s output to all of the channels through where documentation is published, is part of the documentation’s publishing workflow. The authoring experience is generally promoted in demos of documentation tools, but when the documentation writers are putting the tool through its paces, the publishing workflow is what matters most. If the documentation platform does not have the output management feature set designed to manage the various output required by the publishing channels of a company, then the process of managing the various outputs of the documentation can become a real hassle. The writer would have to fix the up-to-the minute changes to the printed documentation every time there are changes to the documentation, and review the web help until it is accurate as well. The writer would have to fix and update the shared chunks of content in all of the formats (print, web, and others) every time there are any changes to that content. If the writer were to copy and paste the updated content in each of the formats every time there are updates to the shared chunks of content, then the hassle of managing the outputs of the documentation would be significantly reduced.

Managing Output across channels is a very complicated process for Managing Documentation. Many platforms for Managing Documentation are not designed to manage such a task and for that reason, when a section of the output is fixed to look proper in a PDF, then subsequent changes made in a shared section of the authored content could cause the web-based output to require writer review as well as review of the previously PDF fixed output. Writers can easily fall into a pattern of short-term ease and simply copy and paste the content into the other required formats rather than going through the published output awkwardly designed process to try to get the published output to look proper. As time goes by, the process will tend to fall into complete chaos (entropy).

Next up is the publishing process, or how you will be publishing content out to all of the channels that you are supporting. This will make or break the documentation system for you and your writers. In most demos today, the authoring experience is front and center for you to explore and to get a feel for how the documentation system is going to work for you and your writers. However, the publishing process is just as critical and could potentially go south quickly for you. Everyone wants to create nice PDFs of their documentation. But then there is the web help as well. How will that web help be updated? Will it automatically be updated or will there be times where you have to manually go in and make sure that the web help is up to date and looking good as well. Managing multiple channels of output is a huge pain especially if the documentation system that you have chosen was not designed to support the multiple channels of output that you are trying to create and to distribute to your audience. Copy and pasting into separate formats for distribution to different channels of output is far easier than having to deal with the tangles of an output process. Ask your vendor to demonstrate how a single change to a chunk of shared content will be published to both the PDF manual as well as to the web help portal. Watch how many steps that takes. Watch where you will have to intervene in the process in order to make sure that everything is published correctly to both of the different portals.

Evaluate the platforms side by side

Now that you have selected a few platforms that seem to fit your organization’s needs for documentation publishing, you should create a comparison of the few platforms that you feel might work for your organization. This can be used as a filter to decide between two or three strong contenders for your documentation publishing tool. The following points can be used to create a short comparison between two or three tools that you have narrowed down to for your documentation publishing needs.

It really depends on the two tools you are comparing. For the case of MadCap Flare vs Document360, MadCap Software created a page called Making The Switch. On this page authors of Document360 and MadCap Flare document their differences. While both authors publish their blog posts separately on their websites, it is a lot quicker to read their structured differences on this single page instead.

Scalability isn’t just about volume

Many documentation tools say they are “scalable” but that typically means they help save pages of documentation written by individual writers. In reality, there are many dimensions to scalability. Here are a few for your consideration as technical writers on teams: how does your chosen documentation tool support your taxonomy as a growing organization; how will your chosen documentation tool’s templates hold up as writers and managers come and go; how will your chosen documentation tool hold up during times of organizational upheaval.

The other major pitfall most organizations fall into is incorrectly defining what they mean by Scalability. If you are evaluating tools for documentation, you need to realize that the definition of Scalability for your organization will be very different from that of another. What this means is that as your organization grows, your current methodology and current system for documentation should be able to scale as well. For a team using a topic-based architecture, this means that the taxonomy used for organizing topics for a single product line should be able to easily be extended to include new product lines. For teams who create large amounts of documentation that must follow strict formatting rules in order to be of value to end users, a set of templates used for authoring should continue to be used by other authors long after the original author has left the organization. For organizations that go through large amounts of change (such as rapid growth), a system for documentation should be able to handle organization-wide change without requiring a complete system wide migration of all content three months later.

And lastly: there is no single test to determine whether or not a vendor’s documentation tools will scale for you and your team. I wish there were but I am unable to think of one offhand. So while I can tell you to ask a vendor of documentation tools for customers who have grown out of their software, I have no idea what you will be able to learn from that. You can only hope.

One thing most teams get completely backwards

(And I say this having watched it happen more than once, from close range.)

I see this often enough to make me shake my head. A team chooses a documentation platform first, then tries to work out the necessary governance around the content once it’s been published to the platform. In reverse of how it should be, the team’s content structure, views on content ownership, and process for content review should determine the functionality that the documentation platform will support. After the team’s content has been published to the documentation platform, the platform becomes a rigid architecture, quite unlike the flexible architecture it supported during the demo of the tool.

Which brings me back to the point at the top of the post and to the great post from my colleague above. The tool that your team uses for documentation is perfectly good or bad, right? It is the work processes and review/ownership of content that are being forced into a box created by the documentation tool. A box that can be made to fit if all the processes are bent and folded to get them to fit perfectly in the box. And when they are in the box they feel ‘off’.

Document your internal process early in the process. It does not have to be perfect, but a rough ‘as is’ process for your future self to look back on is far better than nothing.