Your README Is Lying to New Contributors

Here's an experiment: pick five repos you starred in the last year. Clone one. Follow the README's setup instructions exactly. I'll wait.

How many worked on the first try? In my experience, maybe two. The rest have that familiar smell — an install step that references a script that was renamed three months ago, a config example with fields that no longer exist, a "quickstart" that quietly assumes a version of a dependency from 2024.

This isn't a moral failing. It's structural. And it's costing us more than we admit.

The onboarding tax

A new contributor's first hour with your project is the most fragile hour in open source. They're motivated, curious, and one broken npm install away from closing the tab. Every stale instruction in your README is a small betrayal of that motivation. Multiply by every person who ever cloned the repo, and README rot is one of the most expensive bugs in software — it just doesn't show up in your issue tracker, because the people it hurt never filed an issue. They just left.

Why docs-as-code didn't save us

The docs-as-code movement had the right instinct: treat documentation like code, version it, review it. But it kept the fundamental flaw — a human still has to write the update. We added linting for markdown and called it progress, but the README still goes stale the moment a PR merges that nobody bothered to document. Docs-as-code made docs reviewable. It never made them automatic.

The uncomfortable truth: documentation that depends on human diligence will always lag behind code that doesn't. Code has tests, CI, and compilers enforcing correctness. Docs have good intentions.

Docs as a side effect

The way out is to stop treating doc updates as a separate task and start treating them as a side effect of the thing developers already do: pushing code. Every push already contains everything needed to update the docs — the diff is the changelog, it just needs translating into human language. That's a job AI is genuinely good at, and it's a job that should run in CI, not in someone's head at 11pm.

This is the bet I made building ReadmeForge: a GitHub Action that watches your pushes, diffs them, and proposes README updates as pull requests — review-first, so nothing merges without a human glance. No API key to configure, because the key lives server-side (I'm a solo dev; I have opinions about secret sprawl). Free for public repos, because the repos that need this most are the ones with the least maintenance budget.

I'm not going to pretend it's a solved problem. AI-generated docs need review — that's why the default mode opens a PR instead of committing directly. Sometimes the bot updates a section you'd rather rewrite by hand. Fine. The goal was never perfect docs. The goal is docs that are less wrong than yesterday, automatically, forever.

The real fix is cultural, but culture needs tooling

We tell new contributors "PRs welcome, and please update the docs." Then we're surprised when they don't. What if the docs updated themselves and the contributor's job was just to approve? That's a smaller ask, and smaller asks get done.

Your README is the front door of your project. Right now, for a lot of repos, the front door is stuck and the welcome mat is from 2023. You can keep blaming human nature, or you can automate the part human nature is bad at.

https://readmeforge-app.netlify.app/ — if you want to see the side-effect approach in action.