How to write a README developers actually read
The anatomy of a README that works: the one-liner, the quick start that survives copy-paste, the first-screen rule, and the sections that earn trust — plus a free generator grounded in your actual repo.
Your README is the product page of your repository. A visitor lands, gives it somewhere between five and thirty seconds, and decides to stay, star, or vanish. Most READMEs lose that decision not because the project is weak but because the first screen answers the wrong question — what the author is proud of, instead of what the visitor needs: what is this, is it for me, and can I try it in under two minutes. This is the anatomy of a README that survives the decision.
The first screen decides everything
Everything above the fold should answer three questions in order: what it does (one line, verb-first), who it is for (the specific kind of developer or project), and how to try it (a quick start that works when pasted). Badges, animated logos and center-aligned ascii art push those answers below the fold and cost you visitors who never scroll. A useful discipline: screenshot your README's first screen and ask a friend to say back what the project does. If they hesitate, the one-liner is broken, not the friend.
The one-liner and the name line
Lead with a single sentence in the form [Name] is a [category] that [differentiator] — for example, "fastify-auth is a token auth plugin for Fastify that ships JWT sessions with two lines of setup." Category words do real work: they let the visitor file the project mentally in one second. Avoid comparative hype ("blazingly fast", "best-in-class") — specific numbers ("handles 20k req/s on a $5 VPS") build more trust than superlatives ever will.
The quick start that survives copy-paste
The quick start is the highest-value block in any README, and the most commonly broken. It should be a single fenced code block a stranger can paste into a terminal with zero edits — install, minimal config, run, and one line of expected output as a comment. Test it in a clean environment after every breaking change; a quick start that fails is worse than none, because it teaches visitors your project does not work. If setup legitimately needs prerequisites, state them above the block in one line, not in a paragraph below it.
| Section | Job it does | Length rule |
|---|---|---|
| One-liner | What + who + differentiator | 1 sentence, first screen |
| Quick start | From zero to running | 1 code block, paste-runnable |
| Minimal example | The happy path in code | 10-30 lines |
| Installation | Non-trivial setups, options | Only what differs from quick start |
| Status + roadmap | Honest maturity signals | 3-5 bullets |
| Contributing + license | Permission structure | Short, linked |
Sections that earn trust
After the essentials, three sections separate maintained projects from abandoned ones. An honest status block ("stable and used in production since 2024" or "alpha — API will change") sets expectations better than any badge wall. A minimal example showing the happy path in real code — not fragments — lets developers judge whether the interface fits their brain. And a contributing section that names the actual first step ("open an issue before your first PR") converts interested visitors into contributors instead of silent forks. Skip the philosophy section; nobody installs a worldview.
Badges: signal, not jewelry
Badges are compressed facts, and only facts worth compressing: build status, coverage, latest version, license. A row of six decoration badges (coffee, stars, visitor counts) communicates that the author optimizes for appearance — the opposite of the trust a README exists to build. If your CI is green and your version is current, three badges say more than thirty.
Keeping it true
A README decays at the speed of the project that outgrows it: commands change, options move, screenshots go stale. The sustainable fix is a maintenance habit, not a rewrite — every time a release changes setup or usage, spend the same two minutes updating the quick start that you spent testing it. Projects that skip this accumulate a README that confidently describes last year's interface, which is worse than a sparse one: it wastes the visitor's trust at the exact moment they tried to act on it.
The 30-second audit: open your README, start a timer, and note everything a stranger could have learned by the time it hits zero. If the list does not include what it does and how to run it, fix the first screen before touching anything else.
Writing it from the repository
You can draft all of this by hand in an hour, or start from what the code already says: the ToolFolio AI README Generator reads a public GitHub repository's actual files — manifest, entry points, test scripts — and writes a README grounded in real dependencies and real commands, never inventing features. It is free, requires no sign-up, and pairs well with a manual pass: generated structure first, your voice and judgment on top.
Questions people ask
What makes a good README?
Six things in order: a one-line description of what the project does, a quick-start that works when copy-pasted, a minimal working example, installation for the common case, honest status and license. Everything else — badges, screenshots, long API docs — is optional decoration that must never push the essentials below the first screen.
How long should a README be?
As long as it needs to be for a stranger to succeed, and no longer. For most projects that is 100 to 400 lines. If it grows past that, move the tutorials and API detail into a docs folder and link them; the README stays the front door, not the whole house.
Should I write the README before the code?
Yes for the top half — writing the one-liner and quick start first forces you to name the project's purpose and simplify its interface. No for the rest: feature lists and examples written before the code exists are fiction that drifts from reality within a week.
Do people actually read READMEs?
The first screen, always — that is where the decide-to-stay-or-leave happens. The rest is read on demand, when something breaks or the quick start fails. Design for both: a first screen that sells, and a body that rescues.
Can a tool write my README from my repository?
The ToolFolio AI README Generator reads a public GitHub repo's actual files and writes a README grounded in what is really there — real dependencies, real commands, no invented features. Free, no sign-up, about 3 runs per day.
Generate yours from the repo — free
Point the AI README Generator at any public GitHub repository. It reads the real files — package manifests, entry points, test commands — and writes a README grounded in what is actually there. Free, no sign-up.
Open the AI README Generator →