Old HAT: time to switch from a Help Authoring Tool to a CCMS?

Recently Paligo has attracted more and more interest from users of some of the traditional Help Authoring tools, and the question keeps popping up:

“What distinguishes Paligo (and similar systems) from these HAT tools?”

Paligo was really developed to offer a more affordable and modern cloud-based option to the enterprise-level component content management systems (CCMS) for technical authoring – the types of systems that costs hundreds of thousands of dollars just to get your foot in the door – so we hadn’t actually considered the comparison to Help Authoring tools all that much.

But when looking at it from the perspective of users of Help Authoring tools, the question certainly makes sense. So I set down to try to define some of the points at least that sets a CCMS off from a HAT tool.

If you haven’t yet heard the terms “HAT” and “CCMS”, here are a couple of very brief definitions:

“HAT” is a common abbreviation for a “Help Authoring Tool”, usually a tool for creating multiple outputs, such as online help, print, and more. The HAT tools also have features to allow you to reuse your content (single-sourcing).

“CCMS” stands for “Component Content Management System” and is, as the name suggests, a system for managing content. The “component” part is the key differentiator from other types of content management systems (such as those for managing websites). You manage your content at a very granular level, such as topics or even text fragments and single words, in order to reuse that content efficiently.

Besides the fact that a CCMS obviously offers content management in a way a HAT tool doesn’t, it does share many of the same core purposes as a HAT: to reuse content from a “single source of truth”, and offer built-in authoring and multi-channel publishing. It can certainly be used just the same way as a HAT if that’s all you need.

So what’s the difference?

I’m not going to pretend to be able to give a full technical explanation of everything that a CCMS is here, and how it differs from HAT tools. Nor does everything in here apply to all HAT tools or all CCMS tools. But I want to explore some of the key points to help clarify what the benefits of a CCMS can be.

Let’s start with one of the key differences between a HAT and a CCMS:

It’s all about precision control of your content.

A traditional HAT tool is built on the good old file system paradigm. I.e you manage your content as files in folders on your computer’s file system. This can be convenient and familiar. But managing files can quickly become a mess when the complexity of the content increases, and that brings lots of disadvantages as I’ll try to describe below.

A CCMS, on the other hand, can store and manage your content not as files but as small components of content (down to the smallest text fragments) in a database. This has significant implications and benefits.

Granular components instead of files

To understand the difference, consider an analogy for financial data. If you have accounting data in Excel spreadsheets stored on your file system, they are separate files with no direct relationship between the data between them. If you moved your
financial data into an accounting system, it would get you all that data into a database, where you can all of a sudden manipulate them and calculate figures on each piece of data and its relationship to other data, generating reports and more.

A CCMS does the same thing for your technical documentation: it manages your content not as separate files, but as granular components of content where each piece of content “knows” its relation to other pieces of content.

And this is not limited to larger pieces of content like topics, but down to the smallest granular pieces such as variables or text fragments (as in the example below). You can see exactly where topics, images, text fragments, and variables are used, if it has links to it or from it, and so on.

This puts you in control of your content. It also makes it easier to find all your precious content, which is especially important when you have started breaking up your content into small chunks to make it reusable, and when things start to scale.

Link management

You also don’t have to bother with fiddly file names to keep things together in a CCMS, as you would in a HAT. File names have no relevance in a CCMS. Links are automatically kept track of by the system, no matter how much you move your topics or images around, rename resources, and so on, because in the system they are linked to database ids, not to file names.

I’m just scratching the surface of the possibilities available when managing content in a database-driven environment instead of a file system, but I hope it shows the basic idea.

What is a content model, you may ask? Well, it’s the underlying structure you use when creating your structured authoring. You can think of it as similar to a template that specifies what kind of content you can create, e.g paragraphs, titles, lists and procedures, tables, examples, etc.

Although this is not a mandatory defining feature of a CCMS, most CCMS applications use some flavor of XML. While several HAT tools claim to do so too, in most cases it’s not really XML, but rather a customized version of HTML (or XHTML, but for these purposes that makes no difference).

The Chaos of HTML

Because the HAT content model is usually HTML, it means the content model is too lax. Pretty much anything goes. It also does not have the logical structure most XML models have, but often a rather flat structure with one element after the other. The levels of sections of content is hardcoded into the heading element (h1, h2, etc), but there’s nothing stopping you from creating an inconsistent structure.

(Although both CCMS and HAT tools usually have WYSIWYG editing, the examples below show the markup code for demonstration purposes)

Note that there are ways to structure it more logically, but it is completely up to the user. The content model doesn’t help you. The loose structure of HTML in HAT tools will create content that can vary too much between companies and even individual users in the same company. That lack of structure will lead to serious problems as soon as your documentation starts to scale.

This has important implications: HTML is not really made for structured authoring. This means a HAT tool based on it must try to tweak it into doing more complex things, often creating a content model that starts looking like a patchwork. Some things will be impossible or difficult to achieve.

The clean structure of XML

Paligo uses a content model that is based on a modified (“topic-based”) version of DocBook. This XML content model is quite flexible compared to some others like DITA. But it has the same clear content rules that you can rely on to be stable and consistently used, as the content model be enforced to help you create valid content.

These are just some very simple examples, and as I mentioned, using XML is not exclusive to a CCMS. You could use it in a standalone XML editor too. But the point is XML is typically the model used in a CCMS, and something such a system can use to manage the content very efficiently.

Another advantage with a good CCMS is built-in workflow management. Now, you can always get certain parts of a workflow with a HAT using 3rd party tools, but there are significant benefits to having one built-in and made just for technical writers (and their SME reviewers, translators, etc).

If you want version control in a HAT, it will usually be based on a 3rd party tool like Git or Subversion. Those are fine version control systems. But they are not made for technical writers, especially writers that need to collaborate. They are designed for software developers.

At their core, version control systems like Git or Subversion don’t have check-in and check-out. Instead they use something called the “conflict resolution” strategy. I.e two people can work on the same file at the same time, and if there are conflicts, they need to be resolved when they “commit” the changes.

If you got a cold chill running down your spine when you read that, you are not alone! Most technical writers I know abhor this, and many may need to run over to the developers to get help resolving the conflict.

For a technical authoring environment, it is much better to use the “lockout” strategy using check-in and check-out. When you check out a topic, only you can edit it at that time.

The content in the CCMS will also go through workflow stages to manage the content life cycle for reviews etc, and at the same time keep your content intact while being in translation or released, for example.

There are many more things that make a built-in workflow more suitable for technical writers too, like easy revision rollback, release management with stored snapshots in time, as well as version branching specifically adapted to the reuse of content. In
short, made for technical writing.

A CCMS also gives you a common environment for all users, directly sharing and working on the same content. You have everybody working “on the same page” so to speak. It’s not files spread out on individual computers with manual ways of keeping track. Besides the greater stability this gives in terms of the “single source of truth”, you also get the benefit of making sure each user knows what is going on with the content.

For review workflows, it also means both the writers and the reviewers can manage their assignments in the same space, and even see comments and updates in real time when reviews are in progress. Reviewers can even apply the profiling/filtering to see exactly what their “own” content is about.

Compared to a HAT, where reviewing often means shuffling lots of files around (with or without some semi-manual way of tracking it), this has tremendous benefits.

To many, the process of translation management is where the benefits of a CCMS becomes very apparent. A full-fledged CCMS will handle that otherwise very costly and laborious process of managing your content in different languages. In a HAT tool, you will often have some functionality to deal with translations too. But the problem is that it is still file based. Translation management done like that will often become a great hassle. If you translate to 27 languages, working in a HAT and dependent on a file system, keeping track of all the files, versions, and deliveries can easily become a nightmare.

Also, translators will work in their own environments, using their preferred systems. So providing your own translation tool is often not the answer.

What’s more important is for the authoring platform to:

• manage translations
• be able to show how much has been translated
• show what has been translated, and
• automatically make sure you only send new content for translation.
• etc…

When you have the CCMS managing translations as database relations, there are no duplicated files in the system. Each topic keeps track of its own translations (no separate files), and can export and import these in a standardized (XML-based) XLIFF format specifically made for any major translation software. A CCMS like Paligo can even send it directly to translation systems as tasks.

Let me finish by clarifying one thing: Although I’m describing some of the benefits of a CCMS over a HAT tool, I’m not saying that there are no good HAT tools. Some of them have lots of good features for reuse of content too. For some people, a CCMS may be overkill, and if your single-sourcing and content management needs aren’t too complex, and a HAT tool serves you well, then great. But if you do feel the need for the greater control, collaboration, and content management possibilities offered by a CCMS, now may be the time to look into it.

In the past, when a CCMS used to be a luxury only large enterprises could afford, pricing would have been one of the obvious differences to list in an article like this. But that’s no longer true. Now that there are CCMS applications that don’t break the bank anymore, even small businesses and single writers have the chance to benefit from such features.

I’ve tried to show some of the differences between a CCMS and a HAT tool. But it’s a complex subject, and I don’t think I can really do it justice in a single article. In the end, the only way to really see the difference a CCMS can make is to experience it for yourself, so I highly recommend signing up for a free trial of Paligo.