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: describe how the system works and what to look out for, verified against the code; the code stays the authority on how it is implemented. The deliverable is a docs tree the next engineer trusts and the next refactor leaves untouched: only changed behavior or a new feature sends anyone back to edit it.

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; noting the oddity does not (see quirks and defects).

Survey before prose

Do not start writing at the first interesting file. First enumerate the system's surfaces: