Glossary
Documentation accuracy
Definition
Documentation accuracy is the degree to which the claims a set of documentation makes — parameter names, defaults, command syntax, response shapes, described behavior — match what the software actually does. It is usually expressed as the number of claims that don't hold, or as the share of checked claims that do.
It is not documentation coverage
The two are measured together and confused constantly, but they answer different questions.
Coverage asks whether a thing is described. Accuracy asks whether the description is true. An endpoint can be fully documented and wrong on every line: the page exists, the parameter it names was renamed two releases ago, and the example returns an error.
The confusion is costly because coverage is easier to see. A page either exists or it doesn't. Whether what it says still holds requires checking it against the software, so most teams never do — and a high coverage number quietly stands in for a correctness number nobody measured.
What counts as a claim
Accuracy is only meaningful if you know what is being checked. A claim is any statement a reader could act on and be wrong:
- Names and signatures — endpoints, parameters, flags, fields, function arguments and their types
- Defaults and limits — the value a setting takes when unset, page sizes, rate limits, timeouts
- Commands and examples — every snippet a reader might paste and run
- Response and error shapes — what comes back, including what comes back when the system refuses
- Behavior — "this call is idempotent," "deleting a project removes its keys," "retries three times"
Prose that explains why something exists is not a claim. Anything a reader or an agent will execute, configure or rely on is.
Why accuracy decays even when nobody touches the docs
Documentation becomes wrong without anyone editing it. Every change to the code is a potential change to a claim somewhere else: a default is tuned, a parameter is renamed, a response gains a field, an error code is split in two. None of that fails a build when the page describing it goes stale.
So accuracy is not a property a page has once and keeps. It decays at the rate the code changes, and the decay is invisible from the page itself — it reads exactly as confidently on the day it stops being true. That is the mechanism behind documentation drift.
What a good number looks like
The target is zero known inaccuracies, but the useful questions are where, and how you know:
- Zero on the paths users hit first. A wrong authentication example costs more than a stale description of an obscure flag. Accuracy on getting started, authentication and the primary endpoints is not negotiable.
- Measured per release, not per audit. A number checked last quarter describes code that no longer exists.
- Findings, not a percentage. "96% accurate" sounds reassuring and tells no one what to fix. "Four claims don't hold, and here they are" is a work queue.
Accuracy is the other half of the measurement
Accuracy without coverage measures a subset — the docs you have may all be right while half the product goes undescribed. Coverage without accuracy measures effort — everything is described, and nobody knows how much of it is true.
Together they answer the question a reader actually has: is everything I need here, and can I trust it? Either number alone answers half.
Go deeper
Questions people ask
Is accurate documentation the same as up-to-date documentation?
No. "Up to date" usually means recently edited. A page can be edited last week and still be wrong, and a page untouched for a year can still be right if the code it describes hasn't changed. Accuracy is measured against the software, not the calendar.
Can documentation accuracy be measured automatically?
Largely, yes. Claims about names, signatures and defaults can be compared against the source. Claims about behavior — what a command actually returns — have to be exercised against a running deployment, which is what runtime validation does. Checking by hand works once; it does not survive a weekly release cadence.
Why does accuracy matter more now that AI agents read documentation?
A human reader who hits a wrong example usually notices and works around it. An agent treats the documentation as ground truth and acts on it immediately — it calls the renamed parameter, sets the outdated default, and fails in ways that are hard to trace. Inaccurate docs used to cost reader time; now they produce wrong actions.
What should we do with a list of inaccuracies?
Fix them in order of what readers reach first, not in the order they were found. Then make the check recurring, because the next release will create new ones.