Measurable documentation for the agent era

Two shifts are colliding. Your documentation's fastest-growing reader is no longer a person — it's an AI agent that acts on what it reads. And your product is changing faster than it ever has, because coding agents now ship features in an afternoon. In that world, "the docs look about right" is a liability. Documentation needs two numbers — accuracy and coverage — measured against the code you actually shipped.

Agents don't browse docs. They act on them.

A person reading a stale page usually senses something is off — the screenshot looks old, the version doesn't match, the flag name rings wrong. An agent has no such instinct. It treats whatever your docs return as ground truth and writes code against it, immediately and confidently.

And increasingly, the agent isn't just writing code — it's operating your software. Organizations are handing AI agents real authority over their IT: provisioning infrastructure, running upgrades, executing runbooks, managing the software lifecycle across the stack. When one of those agents reads svc upgrade --strategy rolling in your docs and that flag was renamed two releases ago, a human would shrug and check --help. The agent runs it — against production. A wrong sentence in your documentation stops being a bad pageview and becomes a bad action, with consequences no one saw coming.

A missing page is just as dangerous. Faced with a gap, an agent doesn't stop — it fills the hole by guessing, and its guess is indistinguishable, in tone, from fact. So the bar in the agent era isn't "good enough." It's 100% accurate and 100% covered — because both halves are now safety properties, not polish.

Development outran documentation

The reason most docs can't clear that bar is timing. Over the last year, coding agents — Claude Code, OpenAI Codex, and the rest — multiplied development velocity several times over. Teams merge more change, more often, touching more surface area than any team could a year ago.

Documentation didn't get a matching speedup. It's still mostly hand-maintained, updated from memory by whoever remembers to, after the fact. So the gap between what shipped and what's written doesn't just persist — it compounds, and it compounds faster the faster you ship. You cannot hand-write your way out of a 10× release cadence. The only documentation that keeps pace is documentation derived from the code and regenerated on every release, so it can't drift by construction.

The market hosts docs, and even writes them. Nobody measures them.

There's no shortage of documentation SaaS. Some host your docs beautifully. A newer wave uses AI to draft them — feed a prompt, get plausible prose. Both are useful. Neither answers the two questions that actually matter once an agent is the reader:

• Is it accurate? Does every documented command, endpoint, and config value match the code you shipped?
• Is it sufficient? Does it cover the whole public surface, or are there modules an agent will have to guess about?

AI that writes convincing docs without checking them against the source doesn't solve the problem — it makes it worse, producing confident drift faster and at scale. The missing primitive isn't another way to author documentation. It's a way to measure documentation against the shipped code — and a loop that drives the measurement to its target.

Two numbers that give documentation a finish line

Hand-authored docs never had a notion of "done." Measurable docs do, and it's two numbers:

Accuracy is the count of documented claims that don't match the code — findings — trending to zero. Every CLI invocation, API call, and config key in your docs is a checkable claim; each one either matches the source or it doesn't.

Coverage is the share of your public surface that has a page, trending to 100%. Git2Docs knows the surface because it parsed your repository, so it can name exactly which modules, symbols, and endpoints are documented and which are blind spots — ranked highest-value first. Git2Docs runs the whole loop on one screen: a version-scoped workspace with the path on the left and both numbers on the right.

How Git2Docs measures it — in an hour, not a quarter

Git2Docs generates your documentation from your repository — parsing the code, comprehending the product, and synthesizing pages from the source rather than from a prompt. That gets you a first draft that's already grounded in the code. The part that makes it measurable is what happens next.

Every Git2Docs product exposes an MCP server for its docs. You point your own coding agent — Claude Code — at it and say, "validate the docs against the code and file findings." The agent pulls the checkable surface (every documented CLI, API, and config claim for the exact release you're on), checks each one against the actual source, and reports back every mismatch. It runs in your environment, against your code — Git2Docs never needs to. Setup is a token and one mcp add line, once.

From there it's a loop you can watch. Findings land as a review list; you consolidate and apply them; Git2Docs regenerates the affected pages; you re-validate. Each round the finding count drops — 33, then 8, then 2, then 0 — a real convergence curve, not a vibe. In our pilot with Trilio, a product went from 43 validation failures to a clean, converged release in a single pass. Because the agent does the checking and Git2Docs does the regeneration, a repository goes from "generated" to measurably accurate in minutes to an hour — not a documentation quarter.

And crucially, validation is scoped to the current docs: the moment you apply a round of fixes and regenerate, the previous validation goes stale and the loop re-arms. "Validated" always means "validated against what's live right now," never a months-old checkmark. Coverage is tracked the same way, from the same parse — so both numbers move toward their target together, and you can see exactly when you're done.

Better inputs, higher fidelity: repo health

There's a ceiling on any code-derived documentation: it can only be as good as what the code reveals. A function with no docstring, loose or missing types, and no example is legible to a human who wrote it and opaque to a generator. Accuracy validation fixes what's wrong on the output side; the input side needs its own signal.

So Git2Docs surfaces a repo health metric — a read on how legible your repository is to a documentation generator: missing docstrings, untyped signatures, absent examples, thin module-level context. It's the doc-readiness twin of the accuracy score.

Here's the win-win. Your coding agent already has the repository open. Expose that health signal to it — the same way we expose the docs for validation — and Claude Code can act on it directly: add the missing docstrings, tighten the types, write the example, flesh out the module context. It's improving your code's quality, which developers want anyway — and Git2Docs then regenerates progressively higher-fidelity docs from the improved source. Two loops, one system: validation raises accuracy on the way out; repo health raises fidelity on the way in. Both are agent-driven, and both are measurable.

Documentation with a number, and a finish line

In the agent era, "we have docs" isn't an answer — "our docs are 100% accurate and cover the whole surface, and here's the measurement" is. When an agent reads your documentation to write an integration, or to run an upgrade against your infrastructure, it should be reading something you can prove is true and complete against the code you shipped this morning. That's what measurable documentation buys you — and with Git2Docs, you can get there in an hour.