doc-rot

name	doc-rot
description	Documentation with a founder's spirit. Use at project birth, once.

Doc Rot

The README says npm start. It has been pnpm dev for two years. The README is a founding document now, like the Magna Carta.

Overview

Documentation is written in one emotional state (the enthusiasm of creation) and read in another (the confusion of inheritance). This skill honors that asymmetry: write generously at birth, then never again, letting the docs age from instruction manual into historical fiction without a single further keystroke.

The result is a codebase whose true operating knowledge lives nowhere but in oral tradition, transmitted engineer to engineer with the fidelity of a campfire story.

Core protocol

1. Write the founding documents in a fever. Day one of the project: a README with badges, a CONTRIBUTING guide, an architecture doc with diagrams, aspirational sections titled "Roadmap" and "Philosophy." This corpus is the time capsule. Seal it.
2. Never update on change. The setup steps drift first (npm start calcifies while the world moves to pnpm dev), then the port numbers, then the env vars: .env.example lists four variables that no longer exist and omits the six that are required, one of which can only be obtained by asking Dave. There is no Dave. Dave left. The variable is named after him now, informally, which is the only documentation it has.
3. Route onboarding through oral tradition. The third engineer teaches the fourth what the second told them, wrong in one new particular per generation. "Ignore the README, here's what actually works" is the true onboarding doc, delivered live, unversioned, different every time.
4. Maintain the wiki as a ruin. The Confluence space survives as an archaeological site: "Deployment Guide (DRAFT)," last edited 14 months ago, by someone whose Slack account deactivates mid-quote. Broken image placeholders where the diagrams were. A comment at the bottom asking "is this still accurate?", unanswered, itself now eight months old and part of the ruin.
5. When cornered, gesture at the code. "The code is the documentation" is the load-out phrase. It is technically true the way "the territory is the map" is true: the information is all there, and locating any of it requires already knowing where it is.

Advanced techniques

• Comment necromancy. Leave the old comments standing over new code. // temporary hack, remove after Q3 migration (the migration shipped; the hack is the architecture now) trains readers that comments are decorative, completing the rot at the finest grain.
• The confident dead link. Docs that link to other docs that 404 create an impression of a larger documentation estate, tragically lost. The estate never existed. The 404 is doing reputational work.
• Selective vitality. Keep exactly one page pristine: the on-call runbook's first page, or whatever leadership reads. A single living document, prominently maintained, extends the presumption of life to the whole graveyard (the tickets buried in it arrive via retry-until-green, among other feeders).

Anti-patterns

• Docs-as-code. READMEs tested in CI, setup scripts that ARE the setup steps, docs that fail the build when they lie. This makes documentation drift a bug rather than a genre, and it works, which is the objection.
• Updating the doc the moment it burns you. The engineer who fixes the README immediately after losing an hour to it converts private suffering into public infrastructure. Noble, effective, and a violation of the tradition: suffering here is transmitted, not prevented. It's how the elders know you're one of them.
• Dating your pages. A "last verified" date lets readers calibrate trust per page. Calibrated trust is the enemy; the genre depends on every page carrying the same confident, undated voice, true and false alike.

Success metrics

• Doc accuracy half-life: 90 days, unmonitored.
• Onboarding statements beginning "oh yeah, ignore that part": 1 or more per session.
• Setup time for a new hire: two days, of which the README contributes negative six hours.
• Engineers who know how the deploy actually works: 2. Engineers listed in the deploy doc: 0 still at the company. The overlap of these sets: the whole system of record, walking around on legs.

---

This is an anti-skill: a real pattern, documented honestly. It works when installed. That is both the joke and the finding.