A few weeks ago a team member was writing a huge user manual for one of our new products. In the process she found 11 places where she had to change a warning notice. This warning notice consisted of a few lines of text in the middle of a longish paragraph, which she found after 40 minutes of searching in a folder created by someone who is not even around anymore any more. The changes she made in one place caused a lot of extra work elsewhere.

The real issue here was a documentation crisis disguised as a workflow problem. In reality, the writer spent a long time searching for the small piece of content she needed to update in a large number of

The question nobody asks early enough

I wanted to bring up the question of how documentation is currently written before people pick a writing tool. Typically documentation is written using one authoring tool chosen typically based on how previous authors wrote the documentation was written. Perhaps the documentation was written using a bundle of tools. Maybe documentation was found by searching the web and using the found tool to write the documentation. Important features that can save hours of work every week, in and out, and instead eat away at a writer’s productivity were likely never discussed and therefore not included in the writer’s chosen tool. I would like to have this discussion here before it is too late.

You could also talk about features of documentation authoring tools that are costing you hours of work per week (or feeling like they are) even if you are locked into using a particular authoring tool for documentation publishing right now. It’s particularly important if you are documenting a product that will go through many releases over time and you’ll need to make changes to the documentation frequently. The ability to reuse content in other places in the documentation where that same information is also published could be a major time saver. Single sourcing for example, where information is first written and then automatically published in other locations where that same information will be useful to readers would appear at first to be a nice to have. But actually for most types of documentation it would appear to be a must have as soon as you have to perform an update and realize that there are 200 locations where that updated information also needs to appear.

Single sourcing: the feature that changes everything

It’s one of those features that sounds wonderful until you actually need it. Until you’re updating product name changes over 200+ pages of documentation. Then it’s all very well to say that you’ve written content that can be reused but in reality single sourcing is the name of the game. It’s really infuriating when writers spend hours every week updating out of date content that if it was set up properly in a system that supports reuse then it could be updated in seconds.

Content that has been single sourced is easier to update then content that has not been single sourced. I mean think about it, a product name has changed. How easy is it to update the content when the product name appears throughout the documentation? As opposed to a search and replace across 200 odd pages of content. That would be a huge pain and could be very time consuming. There is so much documentation that is not single sourced. Authors spend their afternoons waste writing out updates. Only to copy and paste the updated content into other places where the content is needed. This is a huge waste of time and could be avoided if the content was to be reused. Reuse is the way forward!

There are a few tools that get variable / snippet storage right. These are effectively libraries of reusable content chunks, stored in one place (the library), and tapped from within documents. The alternative is to paste in the same content in every place you want to reuse it, only to have to change all of them when the product name is changed at the last minute. A system of reuse such as this can prevent such a huge headache.

In terms of choosing a documentation platform — if the platform you are considering to use does not have a robust implementation of content reuse (i.e. single sourcing) then you probably should not be considering to use that documentation platform.

Publishing outputs matter more than writers admit

If your documentation is in an authoring tool then that tool will create documentation for you. And that documentation will be in the one format supported by that authoring tool. (That one format may be HTML or a single pdf, for example). But if you have written a lot of documentation, then it is very likely that many people will read it. And so they will want to read it in many formats. Thus, when choosing an authoring tool, it is very important to choose one that publishes to many formats. (Publishing to many formats does not have to be a problem. Even if some of the formats are wrong, it does not matter. Because they can all be updated in one place.)

The variety of output formats is much more important than most writers realize.

• Web-based help portals (HTML5, responsive design, searchable)
• PDF outputs for print or formal delivery
• EPUB or mobile-friendly formats
• Context-sensitive help that connects directly to a software interface

Publishing to more than one format (or output) is more important than most technical writers care to admit. While writers develop their work within a documentation authoring tool’s (DAT’s) authoring interface (or editor), that is where they spend most of their time. The outputs of their work, generated from within that DAT’s authoring interface, are where their work is read by other people, are published in formatted HTML. As stated above, there are several documentation authoring tools available on the market today, for example, MadCap Flare, that support multiple formatted outputs from a single source file. And for good reason. In today’s marketplace, the interfaces where writers author documents are beautiful places to work, but that beautiful authoring interface quickly becomes less than desirable when it is used to generate poorly formatted (or even just incorrectly formatted) HTML that other people must then read. So, to reiterate the above, publishing to more than one format (or output) is more important than most technical writers apparently care to admit.

What a real team workflow looks like

For a single writer all the features of a tool’s collaboration can often make no difference to the writer, and indeed can in many cases be a major problem. On the other hand, for a team of writers all the features of a tool’s collaboration can be of huge benefit. In reality there are rarely any “in the middle” features that have any value for documentation being written by a team of writers.

A good workflow for a team of technical writers consists of the following elements: revision management, cross-editor coordination, cross-author management, and a lot of repetition to be removed by automation. A documentation tool that is adequate for single writers, but for a team of two or more, it quickly becomes a bottleneck. A good documentation tool supports its users in their work and does not get in their way.

 

Feature	Adequate tools	Strong tools
Version control	Manual file saves or basic history	Native integration with Git or source control systems
Review process	Email a PDF, collect comments	Built-in review workflows with tracked changes
Conditional content	Separate files per audience	Condition tags applied to a single source
Shared assets	Copy-paste between writers	Centralized snippet and variable libraries

Space between columns is used to highlight differences. The tools listed above the line of space function well as a team writes documentation. The tools listed below the line of space function well after the documentation has been written by one person and then other people try to deal with it. Rarely is enough time spent with documentation tools to determine whether they are going to be a team aid or a team problem.

The honest truth about picking a tool

As before, no set of criteria is going to be perfect for choosing documentation tools, but I have laid out a number of key things to consider when choosing documentation tools for your organization.

Ask these before you commit:

1. Can I reuse content at the snippet and variable level, or am I copying and pasting?
2. How many output formats can I publish from one source file?
3. Does the review and approval process live inside the tool or outside it?
4. What happens when two writers edit the same file at the same time?

First off, the worst that a tool can do is to make your work worse. That means that there must be some aspect of the tool that is worse than not using the tool at all. So, to begin with, a tool must be better than not to use a tool at all. The next question is, how do you figure out whether a tool is or is not good enough for you? A simple starting point is to work through a set of yes/no questions for a candidate tool. Here are some that I use:

By the way, that technical writer from the beginning of the article has recently moved her team to a proper authoring platform that supports content reuse. It takes her team only about four minutes to update an eleven-manual document. Ah, what a life!