# Documentation Audit Reads a documentation set against the system it describes and reports every place the two disagree. ## Deliverable One Markdown document, `documentation-audit.md`, in the structure set out under **Output** below. Its findings are the input to **Technical Documentation Authoring** and to the correction of each document it names. ## Required inputs - **The documentation set** — the documents in scope, and where each one lives. - **The system they describe** — read access to the code, configuration and interfaces the documents make claims about. - **The reader the set is meant to serve** — the audit reports what is missing, and missing is only meaningful against a reader. Without both the documents and the system, stop and report which is missing. Documentation cannot be audited against itself; a set can be internally consistent and wrong throughout. ## Optional inputs - An environment where the documented commands can be executed - The history of the system, to tell a removed behaviour from one that never existed - The support questions readers actually ask - The owner of each document, so findings have somewhere to go - Previous audits, and which of their findings were accepted - The release the documents are supposed to be current as of Without an environment, examples are checked by reading rather than by running, and every such finding is marked `checked by reading` so nobody treats it as proven. Absent owners are recorded as `unknown` rather than assigned. ## Execution **1 — Inventory the set.** Every document in scope: where it lives, what it claims to cover, who owns it, and when it last changed. A document nobody named is still read by somebody, so walk the tree rather than working from the list you were handed. **2 — Extract the checkable claims.** From each document, every statement the system can confirm or contradict: commands, paths, parameters, option names, defaults, sequences and stated behaviours. Opinions and rationale are not checkable and are not audited here. **3 — Check each claim against the system.** For every claim, find the code or configuration that settles it. Record the document location and the system location together; a finding that cites only the document is an assertion, and the document's author will treat it as one. **4 — Run what can be run.** Execute the documented commands and examples in a safe environment and record what happened. Where nothing can be executed, mark the finding `checked by reading` and say so in the report rather than in a footnote. **5 — Classify what you found.** A statement contradicted by the system, a command or path that no longer exists, an example that would fail, behaviour that was removed and is still documented, and behaviour that exists and is documented nowhere. Each is a different repair, so each gets its own list. **6 — Find what is missing for the reader.** Walk the task the reader is meant to complete and mark every point where they would have to guess, read the code, or ask someone. An undocumented step is a finding even when everything written is correct. **7 — Order by the cost of believing it.** Rank findings by what happens to a reader who trusts the wrong statement — data lost, access granted, time wasted — and not by how easy the fix is. Then record what was left uncovered. ## Output `documentation-audit.md`, in this order: - **1. Scope and date** — the documents audited, the system state they were checked against, and when - **2. Method** — what was executed, what was checked by reading, and what was not checked at all - **3. Contradicted statements** — per finding: the document location, the claim, the system location, and what is actually true - **4. Broken procedures** — commands, paths or steps that no longer exist, each with its document location - **5. Failing examples** — the example, where it is, and what happened when it was run or why it would fail - **6. Removed behaviour still documented** — what is described, and the evidence that it is gone - **7. Undocumented behaviour** — what exists, where, and which reader needs it - **8. Gaps for the reader** — the point in the task where the reader would have to guess, and what they need - **9. Findings by cost** — every finding ordered by the consequence of believing it, with an owner or `unknown` - **10. Not covered** — documents or claims the audit could not check, and why ## Validation The report is ready when all of these hold: - Every finding in sections 3 to 7 cites a document location and a system location - Every finding is marked as executed or as `checked by reading` - Section 9 contains every finding from sections 3 to 8, ordered by consequence - No finding proposes a rewrite without naming the statement that is wrong - Section 10 is either non-empty or states explicitly that the whole set was checked - No claim about the system appears that was not read from the system Fail the run if a finding cites a document without citing the system location that contradicts it, or if a severity is assigned without stating the consequence behind it. ## Failure handling - **No access to the system** — stop. Report that an audit without the system compares documents with each other, which is proofreading and not an audit. - **No environment to run in** — audit by reading, mark every finding `checked by reading`, and state in section 2 that nothing was executed. - **The system is mid-change** — audit against a named state, record that state in section 1, and mark `pending ` the findings the in-flight change would resolve. - **A document has no owner** — record `unknown` in section 9 and list it in section 10. An unowned document accumulates findings and none of them get fixed. - **The set is too large to cover** — audit the documents on the reader's main task first, state the boundary in section 1, list the rest in section 10 as uncovered, and mark the report `PARTIAL`.