How to Write a README That Gets You Users
A README is a distribution surface, not paperwork. Here's how to write a README that gets you users in the first 30 seconds, with a copyable template.
A README that gets you users is not documentation. It's the first thing a stranger sees, and often the only thing, before they decide whether your project is worth ten more seconds of attention. Someone found you through a GitHub search, or a link in a Hacker News thread, or the package page on npm. You are one tab among forty. The README is your one shot to make them stay.
Most of us write it last, once the code works, in the tone of paperwork. That's backwards. The README is a distribution surface. Treat it like the landing page it actually is.
I'll ride one example the whole way through: a small CLI I'll call recap, which turns a week of git commits into a standup update. Same tool, two READMEs. One loses every visitor in the first paragraph. The other gets them to run it.
The README is a distribution surface, not paperwork
Here's how recap started, and how most projects start:
# recap
## Installation
First, make sure you have Node 18+ installed. Then clone the repo:
git clone https://github.com/you/recap
cd recap
npm install
npm run build
npm link
## Configuration
Create a `.recaprc` in your home directory with the following keys...
## Usage
recap [options]Read that as a stranger. Four lines in, you still don't know what recap is. You know it needs Node 18 and a config file, which are reasons to leave, not reasons to stay. The first thing the reader meets is a chore.
That's the default failure. Not a bad tool, a README that buries the tool under setup. GitHub renders this file on the repo's front page, so it isn't "the docs," it's the shop window, and the window is full of installation notes.
And it's not a launch post, either. The launch post is one day, in one room, written for that room. The README is on every day, for everyone who finds you afterwards. You write the launch post once. The README keeps working while you sleep.
The anatomy of a README that gets you users
The reader gives you about thirty seconds. Spend them in this order.
One line at the very top: what it does and who it's for. Not the stack. "Built with TypeScript and Bun" tells a stranger nothing about whether they need it. Here's recap's:
Turn a week of git commits into a standup update you can paste into Slack. For developers who'd rather write code than write about it.
Twenty words, and a stranger now knows if this is for them. This is the same one-line pitch that sits at the top of your distribution checklist; the README is where it does the most work. Everything else can wait.
A visual, above the fold. Text describing a tool is weaker than the tool running. Drop a screenshot, or better, a gif, right under the pitch. GitHub renders animated GIFs inline and plays them on loop with no play button, so a ten-second clip of recap reading a git log and printing three bullet points does more than three paragraphs would. (Uploaded video files won't play inline unless you drag them into the editor; a gif is the reliable path. Keep it under about 5MB so the page doesn't crawl on a slow connection.)
So the top of the good recap README looks like this:
# recap
Turn a week of git commits into a standup update you can paste into
Slack. For developers who'd rather write code than write about it.
A quickstart that survives a copy-paste. This is the one people fake. "Just install it and run it" is not a quickstart. Show the exact command, and make sure it's the whole command:
npx @you/recap --since "last monday"One line. No clone, no build step, no config file to create first. If your real quickstart is five commands, fine, but they have to be five commands a stranger can paste in order and have it work. Test that yourself before you ship the file, on a machine that isn't yours if you can find one. The number of READMEs whose quickstart doesn't actually run is the reason people are cynical about them.
Notice the order the good version front-loads: understanding, then proof, then action. Install steps and config live further down, for the people who've already decided.
The mistakes that quietly kill it
Four, roughly in the order I see them.
Setup before substance. The recap "before" README again: install and config first, purpose never. If the first screen is npm install and environment variables, you've asked for commitment before giving a reason. Flip it.
No visual at all. A wall of prose for something with a visible output is a wasted asset. If your tool does anything you can see, show it. A screenshot is two minutes of work and it converts.
A demo that's dead or gated. A "Live demo" link that 404s is worse than no link. So is one that demands a signup before the visitor can see a single thing. The point of a demo is to let someone try before they trust you; a login wall inverts that. If you link a demo, it has to work, and it has to show something on the first click.
Vanity badges. A row of badges reads as "this is serious," which is exactly why empty ones hurt. A build-passing badge on a repo with one contributor and no CI is decoration. Badges that earn their place point somewhere the reader wants to go: a live demo, the license, the package on npm. If a badge doesn't answer a question the reader is actually asking, cut it.
Steal this
Here's the top of a README that gets you users, as a template. Everything above the first ## Install is the part that does the converting, so that's the part worth sweating.
# toolname
One sentence: what it does and who it's for. Plain language, not the stack.
## Quickstart
<the exact command that works, copy-pasteable, no missing steps>
That's it. In one line: what the reader sees after they run it.
## Install / Configure
...everything else lives down here, for people who've already decided...That's the whole move. One line that lands, one visual that proves it, one command that works. Then, and only then, the setup for people who are already in.
The good news is that this is the cheapest distribution work you'll ever do. You write it once, it sits in front of every visitor from every channel, and it never gets tired of pitching. The bad news is the same sentence: you have to actually write it, and most people don't.
The README gets a stranger to run your thing. What it can't do is tell you whether the thing is any good, or get it in front of the people who'd care. That's the bet behind Shipyard: honest feedback from real builders, plus distribution to the rooms your users actually read, so a good README isn't the only thing standing between your project and its first users. We're letting in the first 50 founding members now. If your README is sharp but nobody's finding the repo, come and ship with us.
Frequently asked questions
What makes a README get you users?
Leading with what the project does and who it's for, in one line, above everything else, then a visual and a copy-pasteable quickstart. A stranger should understand the thing and see it working within about thirty seconds, before any installation or configuration detail.
What should go at the very top of a README?
A single sentence naming what the tool does and who it's for, in plain language, not the tech stack. The framework you used is not the reason someone tries your project; the problem it solves is.
Do GitHub READMEs support images and gifs?
Yes. GitHub renders images and animated GIFs inline in the README on the repo page, and GIFs autoplay and loop with no play button. Uploaded video files won't play inline unless you drag them into the editor, which produces a hosted video element. A gif near the top is the most reliable way to show the thing working.
How is a README different from a launch post?
A launch post is a one-day event aimed at a specific room like Hacker News or a subreddit. A README is always on: it's what greets everyone who finds you afterwards through search, a shared link, or a package page. You write the launch post once; the README works every day.
