As a follow up to the authoring tools research that I carried out around 3 weeks ago and decided on a tool, the question of what makes a good authoring platform and how one decides on the best authoring tool for use within a business, has been brought to the forefront of my mind. From my research I highlighted a number of points that I looked at in evaluating potential authoring tools, and I’m pretty sure that there would be other potential points that could be used in the evaluation of potential authoring tools for a business, but from my research the list that I created would be a good starting point. And once you have evaluated all of the authoring tools that you feel could be a good choice for your business, it’s likely that there will be a number of tools that scored highly in the evaluation. However, when it comes down to it, there can only be one authoring tool chosen as the best authoring tool for use within a business, and this choice of authoring tool will play a big part in the workflow of the writers, and have a big impact on the writers’ productivity and the quality of the documentation that they are able to produce.

A coffee maker is something that you purchase and hopefully it works for years to come. However, an authoring platform is something that a writer uses and it can have long-lasting effects on the writer and their team for years to come. For this reason, choosing an authoring platform is not something that should be done lightly. A writer needs to do their homework and think through the pros and cons of each tool, and then make a thoughtful decision about which one to choose. That choice can affect how fast a writer is able to publish content, and how the content is going to look when it is published to 40 or more documents. For this reason, it is very important to ask yourself the question: What kind of writer am I when I am at my worst? That is, when it is 4pm, and I am tired, and I am under a lot of pressure to meet a deadline, how will I work with the features of an authoring platform.

## The reuse question is bigger than it looks

I am going to start here because I think most platform evaluations bury this content elsewhere.

Content reuse: the super admin feature. Yes, it’s true. Content reuse is one of those super admin features that from time to time will come up in conversation with other writers and other authors but generally is not something that a writer or author has to deal with very often. But that’s not true. There are many authors and writers who have to deal with content that is copied and pasted into many different documents only to find out that if one piece of information is changed in one document that it doesn’t automatically update everywhere else that information is used. This can be a huge problem for even the best of writers and for even the best of teams. I know this first hand. I’ve seen it happen to good writers. I’ve seen it happen to good teams. And in the end it can bring even the best of teams to its knees.

For highly complex documents that go through many changes single-sourcing or so-called topic-based authoring is a must. All features for conditional text, variables etc. can then be used to their full extent. If your documents have more than one section, spread over more than one file, then tools that allow reuse of entire documents, not just single chapters or sections are absolutely essential for keeping your work organized.Single-sourced documents load much faster in any tool than heaps of unsourced, unlinked, uncontrolled and heavily linked spreadsheets and Word files with manually synchronized and thus outdated content.For sustainable documentation these are the load-bearing walls of your building: good platforms for single-sourced content, clever organization and effective tools to collaborate.

A side-by-side comparison of the major features for making comparisons between platforms is super valuable. Here’s an example for two platforms in roughly the same space: MadCap Flare versus Paligo from Anchormark (MadCap Flare vs Paligo).What I find valuable is that the comparison really forces you to think about how the features of a platform actually compare to one another when they are actually used. That is, beyond the initial ‘ooooh’ in a demo, how the features really work in your daily grind of documentation.

2. Evaluate authoring tools on how they match your real process for writing content

The best authoring tool for you is the one that matches how you actually work today, not how you wish you worked. Many tools promise to support component-based authoring, collaborative documentation development, very complex, multi-media rich documents. But, that does not mean that you should use them for that type of work. The truth is that many authoring tools are not ready for Prime Time for very complex documentation. They can be very good for linear, web-based documentation created by a couple of writers working together on a couple of documents. But, for very complex documentation, you may find that you spend more time managing the tool than you do creating content with the tool. This can be very frustrating.

The tools can only be of value to you if they fit your process. So first you have to define that for yourself. Only then you can start comparing authoring tools. I outlined this process in a previous post: How to define your process. Once you have clarified your process you can start to compare different authoring tools. This is not an easy task, but there are a few things to keep in mind that can make your life easier.

However, before we look at the feature lists of some authoring tools, we first have to determine what type of authoring tool we need.

• How many outputs do you publish to (PDF, web, mobile, print)? More than two and you’ll want robust multi-channel publishing built in, not bolted on as an afterthought.
• Do you reuse content across documents, or does each doc live in its own silo?
• How many people are writing and reviewing simultaneously?
• Do you work with subject matter experts who aren’t writers? (They will not learn XML for you. Accept this now, before it causes conflict.)

Collaboration is where platforms quietly fall apart

More authors on a document that is published at the same time as other authors on the same document(s) means that the amount of work to keep all the updates under control can multiply exponentially. One of the hardest things for document authors to deal with is other authors. To make collaboration work smoothly, the platform needs to support a number of aspects of collaboration. First and foremost, that means supporting a smart review process. Comments from reviewers are typically added to a document as review comments. There are a couple of key things to look for when it comes to review comments. First, comments are added to a document as track changes in a number of platforms. That can make for a very scattered review, with comments from individual reviewers spread throughout the document. Some platforms, on the other hand, collect all the comments from reviewers in one place. That can be better for getting a sense of overall feedback on a document.

Collaboration on documentation is an area where most platforms fail, often for reasons that are not immediately obvious. When you start to add more than a couple of authors to the documentation of a product, it is not enough to track changes to the documentation. A more intelligent way of handling documentation is required. The documentation must support review and the platform must support the creation of workflows for that review. It must also support a robust system of version control. And, it must all be very easy to use. The number of people who author documentation is often greater than the number of people who actually write the documentation in the authoring environment.That other group of people may stick exclusively to their good old Word for life, and a platform must be able to handle that as well. It is not that hard to create a smooth interface between the two environments. Some platforms do this, others treat it as an afterthought, and then try to market it as a leading feature. For a few weeks. Then reality sets in the end sets in.

A quick gut-check before you decide

A framework to look at platform features:

Remember, no single tool is best at every row of the table. As you look at your short list of potential tools to author with, realize that there are trade-offs to be made between points and that in many cases, some points will be more important to you than others.With that said, knowing how a vendor’s tool(s) stack up against another tool on the same row will allow the true nature of the platform to become apparent in the demo rather than the vendor having the ability to attempt to and likely fail to spin the demo to make their tool look better than it actually is.

The costs nobody puts in the budget

Price is an important criterion when reviewing authoring tools. However, for most writers and their managers, price is not the deciding factor. (The only exception to this rule that I know of is for very cheap solutions that seem to offer too good to be true features and functionality. In most cases, the very cheap solution will cost more in the long run.)

Also outside of the price of a tool are the “costs” of a tool. This would be the time to learn a new tool (usually underestimated). Time to migrate from another tool (usually stated to take a few weeks or months to learn a new tool, but actually takes longer).And the worst, the hidden cost, that a tool does not support an output format that is required by the largest client of a team (this can happen at any time, even after contracts have been signed with a vendor). These costs also should be estimated and taken into account during the evaluation process.

As with any major feature, or set of features of this type, within the framework of your authoring environment, there are always risks that must be properly weighed and considered, which is why it is a good idea to give them as much scrutiny as the ANCHORLINKRisk factors associated with flatteryENDANCHOR section above.

And then there is that authoring platform where you turn your thinking into documentation. As I said above, I scrutinize these more than any other feature list (even though I have created a rather good spread sheet to go through all aspects in due course).But as I said above as well, there are occasions when your gut feeling is correct even though your above-mentioned spread sheet did not cover all the relevant points. In the case of my colleague above, she is still happy with the tool she uses for documentation.