Docs that don't rot - keeping engineering knowledge next to the code
Why engineering documentation decays, which docs are worth writing at all, and the structural habits - ownership, proximity, and living status - that keep knowledge truthful.
Apr 27, 2026 · 4 min read · Kash Gohil
Every team has the folder: forty documents, half describing systems that no longer exist, none marked which half. Engineering docs rot because of a structural problem - knowledge is stored far from the work it describes - not because engineers are lazy writers. This post covers which docs are worth writing, why they decay, and the habits that keep them true.
Why does documentation rot?
Three forces, all structural:
Distance. The code changes in git; the doc lives in Notion or a wiki. Nothing connects them, so nothing flags the doc when reality moves. Rot is silent - a doc looks identical the day it's written and the day it's dangerously wrong.
Write-only culture. Docs get written at project start (when energy is high and knowledge is lowest) and never revisited after shipping (when knowledge is highest and energy is gone). The result is documentation of intentions, preserved as if it were documentation of systems.
No owner. A doc without a name on it is everyone's to doubt and no one's to fix. Readers who spot an error have no cheap way to flag it, so they route around the doc instead - and each routed-around doc teaches the team that docs lie.
Which documents are actually worth writing?
Fewer than get written, and different ones. Ranked by value-per-maintenance-hour:
- Decision records (RFCs, ADRs). Why the system is shaped this way. Highest value because they never rot - a decision record is true forever about the moment it captured. This is why RFC-first process quietly produces great documentation as a byproduct.
- Onboarding paths. How to set up, where things live, who owns what. High traffic, fast payback, and rot gets caught quickly because every new person walks the path.
- Runbooks. What to do when X breaks, verified at 3 a.m. by definition. Keep them checklist-shaped.
- Interface contracts. APIs and schemas - ideally generated from code, so they can't drift.
- Architecture overviews. Valuable but the fastest-rotting category; keep them coarse (boxes and arrows, not field lists) so they age gracefully.
The anti-list: prose restating what code says, meeting notes filed as knowledge, and comprehensive wikis maintained "for completeness." Any doc without a plausible future reader costs more than it returns.
What keeps docs truthful?
Put knowledge next to the work. Proximity is the strongest force against rot. Contracts generated from code; runbooks linked from the alert that fires; the spec connected to the issues and PRs that implement it. When the doc lives where the work happens, updating it is a step in the flow, not a separate virtuous act - in Rezee, a spec in Ideate & Design shows live per-section status as linked work merges in Code & Ship, so the document tells you when reality moved (the closed loop again).
Name an owner, per doc. Ownership isn't obligation to keep it perfect - it's a routing address for "this looks wrong." Cheap correction paths (a comment anchored to the exact sentence, as in Discuss & Document) turn every reader into a maintenance sensor.
Date and status-stamp everything. Active / Stale? / Archived plus a last-reviewed date at the top. A doc that admits its age is trustworthy even when old; a doc that hides it poisons the folder. Archive aggressively - an honest archive of ten truthful docs beats a library of eighty maybes.
Write after, not just before. The highest-leverage writing moment is the week after shipping: a short "what we actually built and why it differs from the spec" note. Ten minutes, and it converts the spec from fiction back into record.
How do AI agents change the documentation calculus?
They raise the stakes on both ends. Agents are tireless doc consumers - an agent teammate works dramatically better when decision records and conventions are written down, because written context is the only context it has; teams with good docs get compounding returns from delegation (more on that stack). And agents are decent doc maintainers: drafting the post-ship delta note, flagging docs whose referenced code changed, proposing archive candidates. The structural habits above are exactly what make both directions safe.
FAQ
How much documentation should a small team write?
Less, better-maintained: decision records for one-way choices, one great onboarding path, runbooks for anything that pages, and little else. A useful test - if nobody would notice a doc going stale within a quarter, it probably shouldn't exist.
Docs in the repo or in a wiki?
Proximity wins: contracts and runbooks belong in or generated from the repo; specs and decisions belong wherever they can link to the work - which is the argument for a workspace where docs and code share a system, as we compared in Rezee vs Notion + Slack.
How do you get engineers to actually write?
Lower the bar and attach it to the flow: templates (RFC template here), writing moments tied to existing rituals (spec before build, delta note after ship), and review comments that ask "where's the decision recorded?" the way they ask "where's the test?"
When should a doc be deleted rather than updated?
When its subject no longer exists, or when updating would mean rewriting from scratch - archive it with a pointer to the replacement. Never silently delete decision records; their whole value is being a permanent record of why.