Your README Is Lying to New Contributors

ReadmeForge — Sat, 19 Sep 2026 21:17:58 +0000

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.

Stop Letting Your README Rot: Auto-Sync It on Every Push

ReadmeForge — Sat, 19 Sep 2026 21:17:23 +0000

Stop Letting Your README Rot: Auto-Sync It on Every Push

Every developer has lived this: you clone a repo, follow the README's install instructions, and they don't work. The flags changed. The env vars changed. The quickstart references files that no longer exist. The README is lying to you, and it's nobody's fault — it's just that updating docs is the chore everyone postpones.

I got tired of it, so I built a GitHub Action that keeps the README in sync automatically. Here's how to set it up in about two minutes.

The problem

READMEs rot because they're maintained by hand. The code moves fast; the docs don't. Code review catches broken logic, but nobody reviews whether the README still describes reality after a PR merges. The result: new contributors bounce, users file "docs are wrong" issues, and maintainers sigh.

The fix isn't "write docs more diligently." That's a willpower solution, and willpower doesn't scale. The fix is making doc updates a side effect of pushing code.

The setup

Add this workflow file to your repo (.github/workflows/readme-sync.yml):

name: readme-sync
on:
  push:
    branches: [main]

jobs:
  sync:
    # Prevents the bot from triggering itself
    if: "!contains(github.event.head_commit.message, '[skip readmeforge]')"
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # required — the Action diffs against the previous commit

      - uses: haimhm/readmeforge-action@v1
        with:
          mode: pr

That's it. On every push to main, the Action:

Computes the diff of the push (handles first pushes too, by diffing against the empty tree)
Sends the diff plus your current README to the ReadmeForge API
Opens a pull request with the updated README for you to review

You merge the PR, or you don't. Nothing lands in your repo without your eyes on it — that's the default pr mode. It's review-first by design.

How it actually works

The Action itself is thin on purpose. It collects the diff, ships it to a hosted API over HTTPS, and applies the returned README. The AI key lives on the server side — you never paste an OpenAI/OpenRouter key into your repo secrets, which is the part of other README-sync tools I always hated. One less secret to rotate, one less thing to leak.

The API returns the updated README plus a short changelog of what changed, so the PR body tells you exactly what the bot thinks it updated. If nothing doc-relevant changed, the Action exits quietly with updated=false and touches nothing.

Two config options worth knowing:

mode: pr (default) — opens a review PR. mode: commit pushes directly to the branch (Pro tier only). In commit mode, the bot's commits carry a [skip readmeforge] marker and the if: guard in the workflow above prevents infinite loops.
readme-path — if your docs live somewhere other than README.md.

The free tier

No key, no signup, no card. The free tier gives you 20 syncs a month on public repos. For most side projects that's plenty — it's roughly one sync per working day. If you need private repos, more volume (1,000 syncs/month), or direct-commit mode, there's a Pro tier at $9/month via Gumroad. You add the license key as a repo secret (READMEFORGE_LICENSE_KEY) and pass it in:

- uses: haimhm/readmeforge-action@v1
  with:
    mode: commit
    license-key: ${{ secrets.READMEFORGE_LICENSE_KEY }}

Why this instead of a bot you prompt manually

You could paste your diff into ChatGPT and ask for a README update. That works exactly once, because you'll never do it twice. The whole point is removing the human from the loop: docs update because code moved, not because someone remembered.

Stale READMEs are a tax every new contributor pays. Two minutes of YAML removes it. Try it: https://github.com/marketplace/actions/readmeforge-readme-sync

DEV Community: ReadmeForge

Your README Is Lying to New Contributors

Your README Is Lying to New Contributors

The onboarding tax

Why docs-as-code didn't save us

Docs as a side effect

The real fix is cultural, but culture needs tooling

Stop Letting Your README Rot: Auto-Sync It on Every Push

Stop Letting Your README Rot: Auto-Sync It on Every Push

The problem

The setup

How it actually works

The free tier

Why this instead of a bot you prompt manually