Auditable documentation labels every statement with where it came from: observed in the code, documented by a person, or inferred by a model. Most of what a team needs to know about a system is locked in its source code. Developers can read it, slowly. Managers, business stakeholders, support staff and coding agents cannot, so they rely on documents that are missing, out of date or written for someone else. A wave of AI tools now turns a repository into a wiki. On 1 October 2026 our founder, Amir Pournasserian, compared seventeen of them, and then wrote down the design he would argue for instead. Both pieces are on his site; this note is what they mean for anyone who has to trust AI-written documentation.
What do AI documentation tools leave out?
Of the seventeen tools reviewed, hosted and open source, fourteen write a developer wiki with diagrams and chat, and eleven keep it up to date. Several run on your own machine with your own keys. That part of the market is a commodity, and the open-source bar is high.
The gaps are in who the wikis are for. One tool has a manager view, and it is an analytics product, not a documentation one. Two produce business documentation, and both are built for COBOL-era systems and sold through sales teams. And not one of the seventeen shows which statements were read from the code and which a model inferred. A reader gets fluent prose with no way to know what in it is true.
How does auditable documentation work?
The alternative reads the code once into a fact base, where every fact carries its evidence and one of three labels, and then renders that fact base for each audience.
| Label | Meaning | Examples |
|---|---|---|
| Observed | Derived deterministically from code, configuration or history | A call edge, a complexity score, a churn count |
| Documented | Stated in human-written material | A doc comment, a README statement, an architecture decision record |
| Inferred | Produced by a model | A module summary, a capability description |
Three rules keep the labels honest. The weakest label wins: a fact built from an observed edge and an inferred summary is inferred. No laundering: model output never becomes documented or observed, even on a later run, so the tool cannot promote its own guesses by re-reading them. One way in for human knowledge: human-written material in the source is the only documented input, and a docstring the tool proposes becomes documented only after a person merges it.
The labels appear in every output. No document, diagram or agent answer presents an inferred statement without saying so, and when evidence is missing the output says so instead of filling the gap.
Six principles behind it
- Deterministic first, model last. Indexing spends no model tokens, and a model is used only to summarise, group, name and narrate.
- One fact layer, many views. Documents, diagrams and agent answers never read raw source, only facts.
- Evidence travels with every fact.
- Read-only. The source tree is never modified.
- Local first. The only thing that leaves the machine is text sent to the model the user configured.
- Language-neutral contracts, so the index and the tool surface can be implemented in any language.
Who is it for?
| Reader | What they need | Output |
|---|---|---|
| Developers | How the system is built and where to change it | Developer docs, diagrams |
| Managers | System summary, health, risks, what changed | Manager brief |
| Business team | What the system does, in plain language | Capability catalogue, glossary |
| Operations and support | How to run it and what its errors mean | Operations runbook |
| Coding agents | Structured, cited facts on demand | A knowledge base over MCP |
When a file changes, only what depends on it is regenerated, and what went stale is reported. That is what makes a manager brief something that can stay current rather than a one-off summary.
Why this matters beyond documentation
The same problem sits inside every AI system that answers questions about a business: a fluent answer with no line between what was retrieved and what was composed. The labels are a general answer to it. We built the first version of this thinking into DevGuardian AI, whose Project Memory Bank keeps a persistent, evidenced record of a codebase’s technical debt and review history, and we apply the retrieval side of it in every knowledge system we build: the agent cites by identifier, the server renders from the evidence, and anything the model added is marked as the model’s.
The design, and the full comparison of the seventeen tools, are at the link above. It is a design, not a product, and every claim in it is written as a test someone can fail.