Writing a Great README: The Developer's Checklist
What separates a README that gets stars from one that gets ignored. A practical checklist with examples — the eight sections every project needs and the three most teams skip.
Most READMEs fail for the same reason: they’re written by someone who already knows how the project works. The reader doesn’t. A good README respects that asymmetry and walks a stranger from “what is this” to “I installed it and it worked” in under two minutes.
Here’s the checklist.
1. Headline + one-sentence pitch
The first thing above the fold is the project name, a tagline, and a single sentence that a non-user could repeat back. No jargon, no internal acronyms.
tuput.com — AI dev tools for the stuff you don’t want to prompt for.
That’s it. If someone skims only this, they should be able to tell whether to keep reading.
2. Badges (but only the useful ones)
Build status, npm version, license, and maybe a coverage badge. Skip the decorative ones — they add noise and slow the page.
3. A demo GIF or screenshot
If your project is a CLI, show the output. If it’s a UI, show a 10-second screen recording. GitHub renders animated GIFs. This is the single highest-leverage addition you can make — a README with a GIF converts at roughly 3× the rate of one without.
4. Installation
Copy-pasteable. One block per supported platform. No prose between the commands.
npm install your-package
# or
pip install your-package
# or
brew install your-packageIf there are prerequisites (Node 20+, Python 3.11+), list them in a bullet above the install block. Don’t bury them.
5. Quick start
The smallest possible working example. No flags, no config files — just the shortest path from install to “it runs.”
import { magic } from "your-package";
const result = magic("hello");
console.log(result);
// → "HELLO ✨"If your quick-start requires a config file, that’s a signal the default should probably be more opinionated.
6. Common use cases
Three to five real scenarios, each with a working snippet. This is where you expand on the quick start with the patterns people actually need — auth, error handling, the one tricky flag everyone asks about.
Keep each example under 15 lines. If it’s longer, it probably belongs in examples/.
7. Configuration reference
A table is better than prose for this. Column headers: option name, type, default, description.
| Option | Type | Default | Description |
|---|---|---|---|
timeout | number | 5000 | Request timeout in ms |
retries | number | 3 | Retry count on 5xx errors |
Link to a longer reference file if the options list gets past 15 or so rows.
8. Contributing + license
Two short sections. For contributing, either link to CONTRIBUTING.md or give a one-paragraph summary: “open an issue first, then a PR, run npm test before pushing.” For license, state it and link to the file.
The three sections most teams skip
”Why this exists”
A paragraph on why this project was worth making when the alternatives already exist. Not a diss on competitors — just an honest positioning statement. “X and Y do this too; this one is smaller / faster / less opinionated / supports Z.”
People who land on your repo from a search will always be comparing. Answer the comparison before they have to go hunting for it.
”What this doesn’t do”
Explicit non-goals save everyone time. If your library doesn’t support streaming, doesn’t do retries, or doesn’t work in browsers, say it up front. Nothing kills trust faster than someone installing your package and discovering a gap you knew about but didn’t mention.
A changelog link
Link to CHANGELOG.md or your GitHub releases. Users picking between versions need to know what changed.
Tone and length
Keep it short. The README is not the reference manual — it’s the front door. If you find yourself writing the tenth paragraph about a single feature, that feature needs its own doc file.
Voice-wise: plain, direct, second person. “Install X. Then run Y.” Not “Users should proceed to install X, following which they may invoke Y.”
The structure in one block
# project-name
> One-sentence tagline.
[badges]
[demo gif]
## Install
## Quick start
## Usage
### Common use case 1
### Common use case 2
## Configuration
## Why this exists
## What this doesn't do
## Contributing
## LicenseEight headings. Most READMEs should fit in a single screen’s worth of scrolling after the demo GIF.
Starting from a blank file is the hardest part
If you’re staring at an empty README.md, the hardest bit is section structure — which sections to keep, which to skip, what order. Once the skeleton is in place, filling in the copy is fast.
That’s what our README Generator does. Drop in a package.json, a one-paragraph project description, or a link to your code, and it drafts the full README in the structure above. Edit from there — don’t ship the draft, but don’t start from blank either. Free, no sign-up, 5 runs per day.
The one rule
Write the README for the version of you from six months ago who hadn’t seen this project yet. That’s your reader. If the draft doesn’t work for them, it won’t work for anyone.