Documenting legacy codebases

REQUIRED BACKGROUND: the technical-writing skill (hard rules, kind classification, truth rules, style).

Overview

A legacy codebase has one reliable witness: the code at HEAD. Everything else that speaks about it (names, comments, old documents, diagrams, the memory of whoever is left) is testimony. Core principle: document what the system does, with evidence; record intent only as labeled inference; keep what you could not determine as explicit unknowns. The deliverable is a docs tree the next engineer can trust. Reading a whole system with fresh eyes also surfaces defects, so a findings register rides along with the tree.

When to invoke, and not

Invoke when documenting a system that exists and is under-documented: an inherited or acquired codebase, a system whose authors left, a docs tree that no longer matches the code. A "what does this actually do" investigation that must end in documents also qualifies. Do NOT invoke for documenting a change you are making; the core skill and the document-type skills cover documentation-with-change. Not for arguing a rewrite, which is writing-design-docs, fed by these documents. And not for fixing what the grounding finds: the code fix sits outside this plugin; filing the item does not (see the findings register).

Survey before prose

Do not start writing at the first interesting file. First enumerate the public surface, because the inventory decides both the shape of the docs tree and the definition of done: