How to write a README that converts

For most open source projects, the README gets more traffic than the marketing site, and it is usually the only page a visitor reads before deciding. People arrive there from search, from a link in a comment thread, from a package registry, or from a colleague pasting a URL. They arrive with one question: is this worth ten minutes of my time?

A README that converts answers that in the first screenful and then gets out of the way.

Treat the first screenful as the whole pitch

Above the fold on a laptop is roughly the project title, the badge row, and the first ten to fifteen lines of prose. On GitHub's mobile view it is less, and the About sidebar text appears first. Assume a meaningful share of visitors read nothing below that.

Four things have to fit:

1. One sentence saying what it is. Concrete noun first. "A migration tool for Postgres that generates reversible SQL from your schema files." Not "the modern way to think about data."
2. Who it is for, or what it replaces. "For teams who outgrew hand-written migrations but do not want an ORM." This filters out the wrong visitors faster than any feature list.
3. Proof it runs. One image, animated GIF, terminal recording, or short code block showing real output. Real output, not a mockup.
4. The install command, copyable. One line in a fenced code block, positioned so nobody has to scroll to find it. A large share of visitors copy that line before reading a single paragraph.

If those four things are not in the first screenful, everything else you write is working against a reader who has already decided to close the tab.

The order that matches how people read

Beyond the fold, order sections by the sequence in which questions actually occur, not by how your codebase is organised:

1. What is it, who is it for
2. A demo or screenshot
3. Install
4. A minimal working example, complete enough to paste and run
5. How it differs from the obvious alternatives
6. Requirements and supported versions
7. Configuration, with defaults shown
8. Links to full docs, examples, and the issue tracker
9. Contributing, license, and credits

The two most commonly misplaced sections are "why we built this", which belongs near the bottom or in a blog post, and the full API reference, which belongs on a docs site. Both push the install command below the fold.

The minimal example is the highest-leverage paragraph

Most READMEs show a snippet that assumes context the reader does not have: an imported config object defined somewhere else, a client that was initialised in an earlier example, an environment variable never mentioned. The reader pastes it, gets an error, and leaves.

Write the example so that copying the whole block into a fresh file works. Show the imports. Show the output, as a comment or a second block. If setup genuinely requires three steps, number them and show the result of each.

npm i toolname
npx toolname init
npx toolname run ./schema
# → applied 3 migrations in 240ms

Then verify it. Run through your own README verbatim in a clean container or a fresh clone, on a machine that has none of your dotfiles, global installs, or local environment. This one exercise finds more conversion problems than any amount of rewriting, because the gap between "works on my machine" and "works in the README" is where most first-run failures live.

What quietly destroys trust

These are the things experienced developers notice within seconds, most of which nobody tells you about.

• No license file. For anyone working at a company, an unlicensed project is unusable regardless of how good it is. This is the single highest-cost omission in open source.
• Unspecified requirements. No supported language versions, no OS list, no mention that it needs Docker or a specific database version. Readers assume you do not know either.
• "Coming soon" in a feature table. A checklist with half the boxes empty reads as an unfinished project, not an ambitious one. List what works. Put the rest in an issue or a roadmap file.
• A mockup instead of a screenshot. Designed interfaces that do not exist yet are identifiable, and when the reader discovers it, everything else you claimed becomes suspect.
• Benchmarks with no method. "10x faster" with no hardware, dataset, versions, or script is treated as marketing. Publishing the benchmark script converts the same claim into evidence.
• Stale version numbers and dead links. A README referencing v0.3 when the latest release is v1.2, or docs links that 404, says nobody has looked at this page in a year.
• curl … | sh with no alternative. Offer it if you like, but also show the package manager route and link the script so people can read it.
• A wall of badges. A CI status badge and a version badge are informative. Twelve badges, including ones for social accounts and a code-quality grade nobody recognises, push your actual content below the fold and read as decoration.
• Marketing adjectives. "Blazing fast", "elegant", "beautiful", "revolutionary". Every one of them is a claim the reader cannot check, and the accumulation reads as a substitute for substance. Replace each with something measurable or delete it.
• No indication of maturity. Say whether this is production-ready, whether the API is stable, and whether you are using it yourself. Readers will assume the worst if you are silent, and the honest answer costs you nothing.

What to cut

Most READMEs are too long rather than too short. Candidates for deletion:

• The table of contents, unless the file is genuinely long. On short pages it just delays the content.
• The full option reference. Move it to docs and link it. Keep the five options people actually change.
• Long philosophy sections above the install. Worth writing, wrong position.
• A contributor wall, sponsor logos, and star-history charts above anything functional.
• Repeated calls to star the repo. One line at the bottom is fine. Asking three times is off-putting, and stars are a weak signal anyway, as we covered in are GitHub stars a good signal.
• Emoji section headers doing the work of an actual heading. Fine in moderation, not a substitute for a descriptive title.
• Anything you cannot keep current. An out-of-date section is worse than a missing one.

Write the comparison section yourself

The question every visitor has and most READMEs avoid is "how is this different from the thing I already use". If you do not answer it, the reader guesses, or reads someone else's guess in a forum thread.

A good comparison section is short, factual, and admits where the alternative wins:

• Name the two or three real alternatives, including the do-nothing option, which for developer tools is usually a shell script and a cron job.
• Give one line each on the difference in approach, not a feature matrix with your own column full of ticks.
• Say explicitly when someone should use the other thing. "If you need X, use Y, it does that better." This costs you almost no users and buys you a lot of credibility.

This section is also the part of your README most likely to be found by search, because "toolname vs alternative" is how people look. On our side of that, alternatives pages exist for the same reason: people shopping for a tool compare before they install.

Visuals worth including

• A terminal recording for CLIs, kept under 30 seconds and looping. Text must be readable at mobile width, so increase the font size before recording.
• One screenshot of real output for anything with a UI. Crop to the part that matters instead of showing the whole desktop.
• An architecture diagram only if the project's shape is the hard part to explain.

Add alt text for every image, and keep file sizes small, because a README that takes several seconds to paint loses the visitors on slow connections. Our guide to making a product teaser covers recording and exporting these quickly.

Check it the way a stranger would

Before you consider the README done:

• Read it on a phone. Does the install command still appear early?
• Hide the title and read the first sentence alone. Can someone tell what the project does?
• Count the claims a reader cannot verify. Cut or evidence each one.
• Follow the install steps on a clean machine.
• Ask someone who has never seen the project to explain back what it does after 30 seconds.

The last one is the only real test. If they get it wrong, the problem is in your first two sentences, not further down.

The honest takeaway

A README is not documentation and it is not a pitch deck. It is the shortest path from "someone linked this" to "it is running on my machine", and every line that does not shorten that path is competing with the lines that do. Put what it is, who it is for, proof it works, and how to install it in the first screenful, delete the decoration, answer the comparison question honestly, and test the whole thing on a machine that is not yours. The rest of the repository matters too, and the open source launch checklist covers the files and settings that go around it before you list the project anywhere.