Code Documentation Rules

Documentation that's wrong is worse than no documentation, because it's actively misleading and someone has to spend time discovering that before they can trust anything else — write less, keep it near the code, and delete it the moment it stops being true.

README answers install, run, deploy

• A project's README must let a new contributor go from a fresh clone to a running local instance without asking anyone a question — list exact commands (not prose descriptions of commands), required versions, and any setup step that isn't obvious from the code (environment variables, a database seed, a local service dependency).
• Include, near the top: what the project is (one or two sentences), how to install dependencies, how to run it locally, how to run tests, and how to deploy — in that order, since that's the order a new reader needs them.
• Keep the README itself thin and link out to deeper docs for anything long (architecture, API reference) rather than letting the README grow into an unmaintained wall of text that duplicates other docs.

Comments explain why, never what

• Write a comment only when the code's intent isn't obvious from reading it — a comment restating what the next line does (// increment i above i++) adds noise and a second thing to keep in sync with the code.
• Use comments to capture the "why" a reader can't infer: why a non-obvious approach was chosen, why a workaround exists (link the issue/ticket it works around), why a seemingly redundant check is actually load-bearing.
• Delete a comment the moment the code it describes changes in a way that makes the comment wrong — a stale comment actively misleads the next reader, who has no way to know it's outdated without reading the code carefully enough to not need the comment.

Docs live next to code

• Put documentation as close as possible to the code it describes (a module-level doc comment, a README in the same directory as the subsystem it documents) rather than in a separate, disconnected docs site or wiki that's easy to forget to update.
• Reserve a separate top-level docs directory for cross-cutting concerns that don't belong to one module (overall architecture, onboarding, deployment topology) — not for documentation of a specific module's behavior, which belongs with that module.
• When code moves or is deleted, move or delete its colocated documentation in the same change — a doc file left behind after its code is gone is guaranteed to go stale.

Examples that actually run

• Any code example in documentation must be code that's actually executed somewhere (a test, a doctest, a CI-run snippet) — an example that's just prose-adjacent text drifts from reality the first time the API changes and no one notices.
• Prefer generating reference documentation (API signatures, config options) from the code itself (types, docstrings) over hand-maintaining a parallel description that can silently diverge from the implementation.
• When a documented example can't be automatically verified, mark it explicitly as illustrative/pseudocode so a reader doesn't copy-paste it expecting it to run unmodified.

Deleting stale docs beats keeping them

• Delete a doc the moment it's confirmed outdated and not worth the time to fix immediately — a doc marked wrong-but-present is more damaging than no doc, because readers default to trusting written documentation over asking.
• Treat documentation as a liability with an ongoing maintenance cost, not a one-time deliverable — write the minimum that earns its keep, and prune aggressively during any change that touches the area it describes.
• When in doubt whether a doc is still accurate, verify it against the current code before relying on it or pointing someone else to it — don't propagate a doc's claims without checking.

ADRs for decisions

• Record a short Architecture Decision Record for any decision that was genuinely debated (a real alternative existed, trade-offs were weighed) and would be expensive to silently reverse — not for routine implementation choices that follow existing convention.
• Keep an ADR to: the context/problem, the decision, and the consequences/trade-offs accepted — skip a lengthy narrative; the goal is for a future reader to understand why without re-litigating the debate.
• Never edit an ADR to reflect a later reversal — write a new ADR that supersedes it and link both directions, so the history of the decision (and why it changed) stays intact.