documenting-legacy-codebases

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, because the inventory decides both the shape of the docs tree and the definition of done:

• Entry points and processes: executables, services, scheduled jobs, queue consumers, request handlers.
• Commands and endpoints: everything an operator or client can invoke.
• Configuration: every key, flag, and environment variable the code reads.
• Data: schemas, tables, migrations, files on disk, external stores.
• Integrations: every external system touched, with direction and protocol.
• Build and deploy: how the artifact is produced and where it lands.