See it as a diagram
Everything below, as a diagram you can edit. Describe yours and see it in seconds.
No account needed · Editable canvas, not a picture
The decay order: setup steps go first
README sections do not age at the same speed. Setup instructions decay first because they depend on the most volatile facts in the repository: package versions, environment variables, service dependencies, the exact incantation that starts the dev stack. A team that ships weekly changes one of those facts every few weeks, and nobody re-reads the setup section after their own first week.
Badges go next, and they fail in a specific way: platform migrations kill them wholesale. Repositories that moved CI between providers still show the old provider's badge years later, frozen on the status of the last build it ever ran. A dead badge is worse than no badge, because it teaches readers that the green icons mean nothing.
Screenshots and terminal captures age with every UI change but mislead quietly, since they still look plausible. Architecture sections decay slowest in wording and worst in consequence: a reader cannot tell a current diagram from one drawn two years ago, and the architecture section is exactly where new contributors calibrate their mental model of the system.
The new-clone test
The honest measure of README rot is execution, not opinion. Start a container with nothing in it, open the README, and follow it literally from the first line. Every command you have to type that the README did not give you is a defect. Every step that errors is a defect. Write them down instead of silently fixing them as you go, because the list is the finding.
Run it on a 90-day rule: if nobody has followed the README literally in 90 days, assume it is broken until someone proves otherwise. The people closest to the repository are the worst testers, since their shells, dotfiles, and muscle memory fill every gap. A new hire's first day is a free run of this test; collect their notes before the knowledge evaporates.
# The new-clone test: a machine with nothing on it, the README, nothing else. docker run --rm -it ubuntu:24.04 bash # Inside the container, follow the README from line one, literally. # Rules: # 1. Type only commands the README gives you. # 2. Anything you add from memory is a defect. Write it down. # 3. Stop where the README claims you now have a running dev stack.
The parts that can maintain themselves
The durable fix is structural, not heroic. Split the README into content a machine can produce and content only a human can write, then generate the first kind. Three sections convert cleanly.
Badges: point them at a service that reads live state on every view. A shields.io workflow badge queries your CI when the page renders, so it cannot freeze on a migration; if the workflow disappears, the badge visibly errors instead of staying green forever.
CLI help and usage: inject the real output of --help instead of paraphrasing it. A tool like cog re-runs a marked block and rewrites the file in place, so one CI step catches the README drifting from the actual flags.
The architecture section: embed an image URL that re-renders when the diagram changes, instead of pasting an export. A Datadef project shared public serves a permanent image endpoint; GitHub proxies external README images through its Camo cache, which normally follows the origin cache headers, and Datadef serves the image with a five minute cache lifetime, so an edited diagram usually shows up in the README within minutes. The GitHub-specific mechanics have their own page.
<!-- Badge: shields.io reads your CI state on view, zero maintenance -->
<!-- CLI help: cog re-injects the real --help output. Run `cog -r README.md` in CI. -->
<!-- [[[cog
import subprocess, cog
cog.outl("```text")
cog.out(subprocess.run(["acme", "--help"], capture_output=True, text=True).stdout)
cog.outl("```")
]]] -->
<!-- [[[end]]] -->
<!-- Architecture: a live image URL, re-rendered when the diagram changes -->
What cannot maintain itself, and why that is fine
Prose does not generate. The paragraph explaining why the project exists, the tradeoff notes, the warning about the deploy step that looks optional and is not: those live or die on human review. The consolation is that this is the slowest-decaying content in the file. Restructure the README so the volatile facts are generated and the prose carries only slow-moving truth, and the maintenance burden collapses to a handful of paragraphs a quarter.
Be honest about tool scope here. Datadef keeps the diagram current; it does not sync prose, API references, or code comments. A team that wants prose coupled to code review should evaluate a code-coupled docs tool such as Swimm, as a separate decision.
From diagnosis to repair
If the new-clone test produced a defect list, the fixes rank themselves: setup steps first because they gate every new contributor, dead badges next because they poison trust in the whole file, then the architecture section because it silently miscalibrates people for months.
One honesty note on the diagram loop: Datadef does not watch your repository, and nothing detects code changes by itself. An agent connected to the Datadef MCP server (registry name io.datadef/mcp, API key on paid plans) can redraw the diagram from what it reads in the repo, so the update is one command in CI or one request during review. That is the difference between a README section that rots and one that is at most minutes behind its source.
Diagnosis vs repair
FAQ
Why do READMEs go out of date so fast?
How do I tell if a README is outdated?
Which parts of a README can be generated instead of maintained?
Do live images actually update in a GitHub README?
How often should a README be reviewed?