Skip to content
Velloreth
Programming 7 min read

How to Write a README That People Actually Read

A README is a product decision, not documentation duty. The structure that works, what to cut, and the ten-minute test that tells you if yours is broken.

By

A README is read in ten seconds, or not at all

Picture the actual reader. They arrived from a search result, a link in a chat, or a package registry. They have a problem. They are going to give your project roughly ten seconds to prove it is relevant before they close the tab.

In those ten seconds they are asking three questions:

  1. What does this do?
  2. Is it for someone like me?
  3. Can I try it without a big commitment?

Everything above the first scroll must answer those. Everything else in the file is read only by people who already decided yes — and those people will scroll.

Most READMEs fail at this, and they fail by omission rather than by being too long. A 900-line README that never states what the project does is worse than a 40-line one that does.

The structure that works

This order is not arbitrary — it follows the reader’s questions in the sequence they ask them.

1. Project name, one-line description, and status badges. The name as an H1. Then a single sentence: what it is and who it is for. Not “A modern framework for building things” — “A static site generator that turns Markdown into a fast blog with zero JavaScript.” Specific nouns beat adjectives.

Badges (build status, version, licence) belong here, kept to three or four. They are a credibility signal, and twelve badges is worse than none.

2. A screenshot or demo. If the project has any visual output, this is the highest-value element in the whole document. A reader understands a UI in under a second; the same information in prose takes a paragraph and lands less well.

3. Why this exists / what problem it solves. Two or three sentences on the problem, not the solution. This is where you differentiate: what does this do that the obvious alternative does not? Be honest about the alternative — comparing yourself to a tool people already use is more persuasive than pretending none exist.

4. Quickstart. The copy-paste path from nothing to something working.

git clone https://github.com/you/project.git
cd project
npm install
npm run dev

Then state what success looks like: “You should see the site at http://localhost:4321.” Without that line, a reader who sees a blank page cannot tell whether it worked.

5. A minimal usage example. The smallest thing that demonstrates real value. A code block with input and expected output. Resist the urge to show the impressive advanced case — the reader wants to know it works, not what it can do at scale.

6. Installation, in full. Version requirements, package manager variants, platform caveats. This section is where a lot of projects quietly lose people, because the requirements were never written down.

7. Configuration. The environment variables and options, in a table. If the project already validates its configuration, point at the schema rather than duplicating it — environment variables explained covers why that validation belongs in code.

8. Contributing and support. How to run the tests, how to file an issue, where to ask questions. Link CONTRIBUTING.md rather than inlining it.

9. Licence. One line, named explicitly. “MIT” is enough; “see LICENSE” is not, because the reader now has to click.

The quickstart test

Here is a test that finds more problems than any amount of editing: clone your repo into a fresh directory, on a machine that has never built it, and follow your own instructions literally.

Do not use your judgment. If the README says npm install, type exactly that. If a step is missing, do not fill it in from memory — write it down as you discover it.

This catches the failure mode that makes an install section actively harmful: instructions that were true eight months ago. A stale quickstart is worse than no quickstart, because a reader who follows it and fails concludes the project is broken, not that the docs are old.

Two mechanical checks that catch most of it:

  • Every command in the README should be copy-pasteable as written — no ellipses, no <your-token-here> without an explanation of where to get it.
  • Every relative link and image path should resolve. Broken screenshots in a README are extremely common, because the file was renamed and nobody noticed.

What to cut

README length tends to grow by accretion — every contributor adds a section and nobody removes one. These are the sections that earn their removal:

The architecture essay. Four paragraphs on internal design, when the reader wants to run it. Move it to docs/architecture.md and link it.

The exhaustive API reference. If it is exhaustive, it belongs in generated docs that stay in sync with the code. A hand-maintained API list in a README is out of date the moment a signature changes.

The full changelog. That is what CHANGELOG.md and GitHub Releases are for.

The aspirational roadmap. Unless you actively maintain it, a roadmap is a list of promises you will not keep. A “Planned” section with three living items is fine; twenty items from two years ago reads as abandonment.

Marketing superlatives with no content. “Blazingly fast” means nothing without a number. “Builds 1,200 pages in 23 seconds” means something.

Details that quietly do the work

Small things with disproportionate effect on whether someone stays:

Use the words your users search for. If people look for “markdown static site generator”, those words should appear in the first paragraph. This is the same principle as normal page SEO — the Astro SEO checklist applies to a README that ends up rendered on a docs site, and the AEO and GEO guide covers writing for answer engines specifically.

Show output, not just commands. A terminal block with the expected result lets a reader verify at a glance. Side by side, code and its output are far more convincing than either alone.

Say what it does not do. A short “Limitations” section builds enormous trust. A reader who sees their edge case listed knows the author is honest about the rest, and will not waste an afternoon discovering the gap.

Keep the licence line visible. Its absence is a genuine blocker for corporate users, who cannot adopt code without a clear licence.

Write in second person and present tense. “Run the command” not “the user should run the command.” It reads faster and it is shorter.

Include an alternative’s name. Naming the thing you replace tells a searcher immediately whether to keep reading, and it is how people find you in the first place.

Keeping it true

Documentation rots faster than code, because code fails loudly when it is wrong and documentation fails silently. Three habits prevent most of it:

Update the README in the same commit as the behaviour change. A separate “docs” commit never happens. If the change alters how someone runs the project, that is not a complete PR until the README reflects it — the same argument building open source beyond code makes about maintenance work being part of the product.

Test the quickstart in CI. Add a job that runs the exact commands from the README against a clean checkout. This sounds excessive and it is not — it is the only way a quickstart stays true, and it is a five-line workflow.

Delete aggressively. A section about a feature you removed is not neutral; it is a trap. Removing stale content is a contribution of equal value to adding new content.

Minimal and complete

If you take nothing else from this: a README is not documentation about your code. It is the argument for why someone should use your code, followed by the shortest path to doing so.

That means the two tests worth running before you publish are:

The ten-second test — does the top of the file say what this is, who it is for, and why it exists? If a stranger cannot answer all three without scrolling, fix that first.

The clean-machine test — can someone who has never seen this project get it running by following the instructions literally? If not, every other improvement is secondary.

Projects succeed or fail partly on whether people can start. The README is where starting happens.

Frequently asked questions

What should every README contain at minimum?
A one-line description of what the project does, who it is for, a copy-pasteable install and run command, a minimal usage example, the licence, and how to contribute or get help. That is the floor; everything else is optional.
How long should a README be?
Long enough to get someone from zero to a working state, and no longer. For most projects that is 100 to 400 lines. Anything deeper belongs in a docs/ directory or a wiki, linked from the README.
Should the README include screenshots or a demo?
Yes, for anything with a visual result. A screenshot or a short animated demo often communicates more in two seconds than three paragraphs of description, and it is the single highest-leverage addition to a project README.
Where should the README go for a monorepo?
A short root README that explains the overall project and points to per-package READMEs, each of which is complete enough to stand alone. Never assume the reader started at the root.
Does a README affect discoverability?
Yes. Search engines and code-search tools index README content, and the first paragraphs are what appear in results. A clear title and a description containing the words users actually search for materially improve how findable the project is.