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: Show more Installs 1.0K Repository riekelt/technical-writer GitHub Stars 20 First Seen 4 days ago Security Audits Gen Agent Trust Hub Pass Socket Pass Snyk Pass