What Should Technical Writers Expect From Modern Writing Tools?

I was reminded of my colleague’s horror story for documentation teams recently when I read that the new updated warning label had been copy and pasted into 14 documents on 6 different product lines. It took her three weeks to find the last of the old warning labels which were buried in a PDF from 2019 in a folder marked “FINAL_v3_USE THIS ONE” on a Friday afternoon.

I spent the better part of my career writing technical documentation. I have a lot of affection for that career, and for the people who do that work. But the story of my career as a technical writer is the story of my career with tools, and the disasters that those tools have caused me. And that’s a story that the industry is not yet finished telling.

The bar has moved (and most tools haven’t caught up)

One of the main differences between what is possible with documentation right now and what most teams are actually able to do is the way that documents are treated. For decades, documents have been treated as sealed containers of content — a single document, or even a single chapter, of content locked away from all of the other documents on a project. There is no shared content, there is no structured reuse of content, and there is no automated publishing of documentation. Instead, writers are restricted to working in word processors, one document at a time, with the quiet hope that nothing important will change in chapter four.

It is really hard to manage content that is held in a number of disconnected systems. As an example of this, an error is found in a document and corrected. All is well for a short time before the same error is found in seven other documents. Managing content held in separate systems is like playing whack-a-mole blindfolded. The error has been found and corrected in one place but seven more instances have been found.

As before, what we are looking for is a description of what documentation tools actually do today, warts and all. What are the features and limitations of typical documentation tools in 2024, and what can you really expect from a documentation tool? Don’t get sold on a list of features from the past century; read something realistic about the actual use of documentation tools by technical writers all day, every day.

Content reuse: the thing that sounds boring but will change your life

A colleague of mine spent three weeks looking for an outdated warning label that had been copy-pasted into 14 documents across 6 product lines. He found the last copy in a PDF that had not been updated since 2019. The reason that he had taken so long to find it was that it had been copy-pasted into all of the relevant documents, and no one had any idea where to start looking for the outdated warning. In the end, the safety specification changed, and the outdated warning became irrelevant. However, the amount of time that it took to find and update the outdated warning label highlighted a major problem with the way that we manage our content.

A couple of weeks ago, I blogged about how I believe documentation tools for technical writers should support content reuse in some form. Whether this is simple content inclusion or true single-source authoring, the ability to manage large quantities of documentation whilst minimizing redundant work is crucial. A great deal of frustration in documentation writing currently stems from the lack of good documentation tools that support this sort of thing. A lot of tools currently treat each document as a sealed box, and that is simply not sufficient for the sorts of writers who need powerful documentation tools today. Instead, we need documentation tools that support single-source authoring in a fashion that is appropriate to the individual writer. And this should work for large documentation sets. After all, no matter how smart you are, making updates to a chunk of content is always going to be faster when you can update it once and have the changes appear automatically in all of the places where you used that content to write other documents. And that, my friends, is beautiful.

• Variables for product names, version numbers, and company-specific terms
• Snippets or topics that can be reused across different guides and manuals
• Conditional content that shows or hides sections depending on the audience or output format
• A content repository that the whole team can actually find and search

All of the features that I have described so far are not fancy or unusual for documentation tools. They are basic and the minimum that any documentation tool should support. If a tool fails to handle most of these basic documentation tasks then it is not worth using for documentation.

Publishing shouldn’t feel like a separate job

One of the biggest challenges for technical writers is what to do with finished, reviewed documents. The greatest problem is that others want to view the writer’s hard work in different HTML formats, in PDF, on different computers, and on even mobile devices. Why would a writer want to redo their work for these different formats of computers? That is where the writer’s technical writing software comes into play. It is best if the writer can set up templates for the various formats that he/she will be publishing their documents in before he/she begins to write. This way, the writer will be able to focus entirely on his/her technical writing, and leave the formatting for the different formats of computers to the software that he/she is using for his/her technical writing.

Another feature of a modern technical writing software is that it should support the so-called multi-format publishing. This means that the documentation is written once and then it can be published everywhere. Ideally, the output templates are then separated from the content, so that a style change, for example, does not have to be done in every single file. Thus, the writer can fully focus on writing.

Focus on your writing and don’t have to reformat the output for HTML, PDF, etc. as well as a version for mobile devices. Set up the templates for the different output formats separately from the content.

What makes good documentation tools so good (vs great)?

How can I set up review workflows with experts outside of my company?

Feedback during the review process is one of the most important aspects when creating high quality documentation. Therefore, it is important to make sure that the processes do not add too much friction to the feedback given by the subject matter experts (SMEs). In other words, downloading and opening a document, using commenting tools that the SME is not familiar with, and going back and forth by email for feedback should be avoided as much as possible.

Make Reviewing Easy. That’s the main thing. The best documentation tools enable Subject Matter Experts (SME’s) to easily review documents. This means that they are able to review documents in a browser and with the minimum of setup. The comments that they make are then tied to the relevant part of the document so that the author can view them in the correct context. All of the feedback is stored within the document so that it is never lost. It is not sent to the authors email or put in a draft folder for the authors and the SME’s.

This sounds very simple but the differences in quality of feedback between having to download and open up a separate application versus simply clicking on a link in the author wants you to review, is enormous.

Translation! Don’t forget about it!

Translation: While translation is not a feature used by many documentation teams, for those that do, it is a critical aspect of their documentation workflow. If a tool treats translation as an afterthought, it can cost a great deal of time and money in the long run. Writers should look for tools that have support for translation memory, can cleanly export documentation to files that translation software can read, and have a workflow for handing translated documentation off to writers that preserves the document’s original structure.

Lastly, it’s worth confirming whether your tool supports translation memory and the export of clean documentation files that don’t cause any problems with the translation software. Also, check how your tool handles the handoff of documentation content to translators and make sure that the documentation is being translated in a structure that is similar to the original. I recently spent a lot of time and hard work crafting a beautiful set of documentation and when the Spanish and French translations were returned, they were all one very long document and not very useful. I could tell that this was not the intention of the translators and it was very painful.

I apologize for being rather pessimistic, but no single tool is capable of handling all of the above (as I am aware of several very good tools that address most of these issues very seriously and many, many more that do not). So I will not recommend a single tool for all of your documentation here. But I would want to recommend a number of tools very seriously and I would hope that you can feel the differences that there are in very small as well as large ways for your team.

So, ask harder questions of your technical writing tools candidates. How will you handle updates to content used in about 50 odd documents? How will your reviewers use your documentation review tool for the first time? How will you translate your documentation?

Your future Friday-afternoon self will thank you.