{
  "id": 8539877,
  "title": "Your README Is Lying to New Contributors",
  "url": "https://urgent.news/2026/09/19/your-readme-is-lying-to-new-contributors",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-09-19T21:17:58.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/readmeforge/your-readme-is-lying-to-new-contributors-33a9"
  },
  "original_language": "en",
  "account": "Your README is deceiving new contributors to open-source projects. To test this, select five repositories you followed in the last year, clone one, and adhere to its setup instructions. In the author's experience, this works for only two repositories, the rest presenting issues such as outdated scripts, non-existent config fields, and outdated dependencies. This isn't due to any moral failure but rather structural. The onboarding cost is substantial, as a new contributor's first hour with a project is the most vulnerable and can be lost to a simple npm install error. This is what the author refers to as 'README rot,' a costly bug rarely logged as it doesn't appear in the issue tracker, the affected contributors never file complaints, they simply leave. Docs-as-code movement aimed to treat documentation like code, versioning and reviewing it, but it failed to address the core issue: human intervention is still required. Documentation dependent on human diligence lags behind code. Code has tests, CI, and compilers ensuring correctness, while documentation lacks these. The solution is to treat documentation updates as a byproduct of code changes, not a separate task. An AI can be employed to create and propose documentation updates as pull requests, reducing the burden on contributors. This is the concept behind ReadmeForge, a GitHub Action that updates READMEs based on code changes through a CI process. It's free for public repositories and ensures documentation evolves automatically, forever. The ultimate aim is to make documentation less flawed than before, automatically and continuously.",
  "summary": "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…",
  "key_points": [],
  "editors_take": null,
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}