How to Audit Documentation Without Destroying the Team That Writes it

Picture the meeting where leadership announces the documentation audit. You can already see it on the faces in the room. The writers have been here before. Last time there was an "audit," two people were let go and the rest were told to do more with less. The time before that, the whole team was handed a new tool and told the old way wasn't working. Now someone is asking to evaluate the accuracy, completeness, and redundancy of everything they've produced.

The writers are not being paranoid. They're pattern-matching.

And here's the thing: the audit probably does need to happen. Docs that drift out of sync with the product create real operational risk. According to IDC research, document-related challenges account for more than 21% of productivity loss, costing businesses roughly $19,732 per information worker per year. Stack Overflow's developer survey found that 62% of developers spend more than 30 minutes each day searching for answers to poorly documented issues. Inaccurate documentation is not a minor inconvenience. It is a slow leak in the floor of the organization.

So the question isn't whether to audit. It's whether the organization can do it without fracturing the team that keeps the docs alive.

The Thing That Makes Audits Go Wrong

Most documentation audits fail before they start, because the people running them conflate two separate problems.

The first problem is a systems problem: the documentation has drifted, coverage has gaps, and multiple sources are saying different things. The second problem is a performance problem: some writers are better than others, and leadership wants to know who.

These are not the same problem. When you run them together, you get the worst of both. Writers start defending their work instead of diagnosing it. They hide the gaps they know about because surfacing them feels like admitting failure. The audit produces a report that catalogs what's broken, but the team is now less willing to fix it.

Amy Edmondson's research on psychological safety is useful here. Her work shows that teams with high psychological safety are more willing to surface errors, admit uncertainty, and collaborate on solutions. Teams with low psychological safety do the opposite: they protect themselves. An audit that feels like a performance review will reliably produce the second kind of team behavior, right when you need the first.

The fix is to separate these problems explicitly and publicly. Tell the team, before the audit begins, that this is an assessment of the documentation system, not of individual performance. Then mean it. Don't say it and then use the findings to justify headcount decisions. If you do that once, you won't get honest participation in the next one.

What to Actually Measure

Once the framing is right, the measurement question becomes tractable. The goal is to assess whether the documentation is doing its job, not to count words or pages.

Four things matter.

Accuracy against current product state. Does the documentation reflect the software as it exists today? This is the most common failure mode. Products ship, documentation doesn't update, and the gap compounds. The Squarespace engineering team's experience with docs-as-code illustrates why: when documentation lives outside the engineering workflow, it's easy for it to fall behind. When it lives inside the workflow, it's harder to ignore.

Completeness of critical workflows. Are the most important user journeys fully documented? Not all documentation is equally important. A gap in the reference for an obscure API parameter is different from a gap in the onboarding flow. Prioritize by consequence.

Discoverability. Can users find what they need? A document that exists but can't be found is operationally equivalent to a document that doesn't exist. Research on documentation quality consistently identifies usability, including navigation and search, as a core quality dimension alongside accuracy.

Redundancy and drift across sources. Is the same information duplicated in multiple places, with different versions saying different things? This is often the most politically sensitive finding, because it usually means that different teams have been maintaining their own versions of the truth.

What you are not measuring: how long it took to write something, how many documents a person produced, or whether the writing style matches some internal preference. Those are performance metrics. Leave them out of the audit entirely.

Getting the Team to Help You Find the Problems

Here is the part that most audits skip, and it's the most important part.

Participatory evaluation, the practice of involving stakeholders in setting the criteria by which their work will be judged, dramatically increases buy-in and reduces resistance to change. Writers who help define what "good" looks like are far less likely to see the audit as a trap. They're also far more likely to surface the real problems, because they're not trying to protect themselves from a standard they had no hand in creating.

Ask the team: which documents do you think are most critical? Where do you suspect the biggest gaps are? What makes it hard to keep documentation accurate? These are not rhetorical questions. The answers will tell you more than any automated scan.

The blameless postmortem culture that Google and Atlassian have documented in their SRE practices is a useful model here. Atlassian's approach assumes that everyone acted with the best intentions based on the information they had. The goal is to find the systemic failure, not the person who made the mistake. Applied to documentation, this means asking: what process allowed this guide to become inaccurate? Not: who wrote this inaccurate guide?

That reframe changes everything about how the team participates.

The Question About Automation

At some point in the audit, someone will raise the question of automation. Can AI generate or update documentation faster than humans? The answer is yes, for certain categories of content. And the writers in the room know this.

Don't avoid the conversation. Avoiding it only confirms the fear.

BCG's 2026 analysis found that 50 to 55% of US jobs will be reshaped by AI over the next two to three years, with full substitution being much slower than augmentation. MIT Sloan research argues that AI's biggest impact comes from redesigning entire workflows, not automating individual tasks. The organizations that benefit most are the ones that rethink how work is structured, not the ones that simply swap humans for machines.

For documentation teams, the honest version of this conversation looks like: automation can handle volume, the repetitive work of updating parameters, generating release notes, and maintaining reference content. That frees writers to do the work that actually requires judgment: information architecture, user experience, accuracy governance, and the editorial decisions that determine whether documentation is actually useful.

Some organizations have already made this transition. They redirected their top documentation performers into validation, governance, and strategy roles while using automation to handle the volume. That path exists and is worth discussing honestly. Pretending the risk isn't real doesn't protect anyone; it just means the team finds out later, under worse conditions.

Doc Holiday streamlines the process of keeping documentation in sync with the product, with humans in the loop validating output at every stage, which reduces one of the most persistent sources of audit anxiety: the recurring question of whether docs reflect the actual state of the codebase. The structure it provides for validation and scaling means those humans are governing a system rather than manually recreating the same content in five places. For teams facing an audit, that's a meaningful change in what the job actually is.

What the Audit Should Produce

A documentation audit that ends with a report is a documentation audit that failed.

The point is not to catalog what's broken today. The point is to make it easier to keep docs accurate going forward. That means identifying the systemic roadblocks that cause documentation to drift in the first place, and proposing concrete changes to the process that produced those roadblocks.

If the audit surfaces gaps, the output should be a prioritized list of what to fix and a workflow change that makes those gaps less likely to recur. If it surfaces redundancy, the output should be a consolidation plan and a decision about which source will be authoritative going forward. If it surfaces accuracy problems, the output should be a process for keeping documentation in sync with the product, not just a list of pages that need updating.

The best audits leave the team in a better position than they were before. Not just with better documentation, but with a clearer understanding of what they're responsible for, and a system that makes it possible to meet that responsibility.

That's the version worth running.