Open-source projects live or die in the first 30 seconds of their README. And right now a lot of them read like they were generated in one shot: three paragraphs of "seamlessly empowers developers to unlock robust workflows" before anyone learns what the thing actually does.
The tells
-
A mission statement before an install command. Nobody scrolls to find
npm install. - Adjective stacking. "Powerful, flexible, lightweight, modern" — four words, zero information.
- No failure modes. Real docs tell you what breaks. Generated docs only tell you it's great.
- Uniform paragraph length. Every block the same size is a machine fingerprint.
The 3-pass fix
- Lead with the verb. The first line answers what this does and who it's for, in one sentence. Then the install snippet. Everything else moves below the fold.
- Cut 30% of the adjectives. Then cut the ones that survived and aren't measurable. "Fast" is a claim; "renders 10k rows in 40ms" is a fact.
- Add one real thing. A gotcha, a version constraint, a "this won't work if you're behind a corporate proxy". Specifics are the cheapest proof a human shipped this.
Check before you commit
Paste your README intro into a free AI-risk scorer: https://humanizeai-lab.pages.dev/tools/ai-risk-scorer.html — under 40% is the bar I use for anything public-facing. When it comes back high, it's almost always the adjectives.
The fixed prompt set I run docs, changelogs, and PR descriptions through is here: https://felovery.gumroad.com (code FIRST50 = 50% off, no expiry).
Good docs aren't longer. They're less padded.
What's the worst README you've had to reverse-engineer?
Top comments (0)