Why auditing your documentation is a must

If you ask a group of people about the qualities of good documentation, you'll probably get many different answers, but accuracy and ease of reading should be high on everyone's list. Chances are your docs are 100% accurate and super-easy to read the day you publish them, but they inevitably get less so as the product they describe evolves.

That's right, even the docs get old. If that's happening with your content, it's time to do a documentation audit.

What is a documentation audit?

Auditing your docs typically involves:

• Reading the current text and making sure it's still valid by, for example, asking subject-matter experts (SMEs) or testing the documented behavior
• Removing old procedures and outdated information rendered useless by new features
• Simplifying explanations and descriptions that become too complicated as you add new notes and warnings

Taking time for a careful review and rewrite enables you to find and fix the places where your docs just don't do the job anymore. Based on my experience, I'd estimate it takes one to two days of uninterrupted writing time to audit a chapter (not counting the subsequent SME and peer reviews). The amount of time depends on things like how long the chapter is, how much additional research and testing are required, how outdated the content is from a technical point of view, and the writer's experience with this kind of rewriting.

One or two days sounds like a lot of time—you might even think that it's much more than you can afford. Or maybe you'd like to do a doc audit, but your boss doesn't see it as "real work" because it doesn't produce new output. The good news is there are ways to prove that thorough reviews are worth the effort.

How do you measure doc quality?

Producing numbers and graphs is definitely not my favorite thing in the world, but when it comes to proving that the time spent on an audit improved documentation, you can't do without them. At the beginning of this article, I highlighted two important features of good docs: accuracy and ease of reading.

Determining whether your documentation is accurate seems fairly straightforward. Information about a product is accurate if it correctly describes the product's behavior. Instructions are accurate if you can follow them successfully.

On the other hand, measuring ease of reading is considerably trickier. Fortunately, there are tools that can help: readability scores, estimated reading time, and similar data. If you'd like to try them, check out the style command provided by the diction package or websites like readable.io.

The data don't lie

When I used readable.io to compare the readability data for a few chapters before and after an audit, I got stunning results.

The difference between the two versions was most apparent for a product overview chapter, one that describes the product's goal, benefits, and components. The chapter provides only general concept explanations, no procedures.

The astonishing drop in estimated reading time (from 18 minutes to eight) came by cutting down the fluff without mercy and eliminating a lot of duplicate text. For an introductory chapter, it's fine to describe just the basics and link to other chapters or guides for more details.

In another audit, this time for a chapter where procedures prevail over conceptual descriptions, the decrease in reading time was less significant. Nevertheless, getting rid of fluff within sentences still helped make it easier to read.

Doc audits take time, but they are worth it

I've had to justify the merits of audits several times, such as when I was working on three large guides. I got into debates about whether it's worth it to spend time rewriting something that's already out there, especially when we have so much new product functionality to cover, so much new content that needs to be written.

I believe the before and after comparisons above prove it is worth it. Not only is the audited content more reader friendly; because it's often shorter, it's often easier for writers to maintain.

Doing doc audits is an investment: You spend a lot of time reading, rewriting, thinking, and rewriting again. It might seem like a luxury during the planning phase, but if you are working with an outdated docs set, it definitely pays off—especially if your goal is to have top-quality docs.