Quick answer: A good README does three jobs in the first 60 seconds — it says what the project is, who it is for, and how to run it. Put a one-line description, a working Quick Start, and one real usage example above everything else. Installation badges, contributor walls, and project history can all wait. If a developer cannot get your project running from your README alone, the README is not finished.
Most READMEs fail in a predictable way. They open with a paragraph about the author’s journey, list twelve npm badges, and bury the install command somewhere below a screenshot from two versions ago. The reader does the math every developer does: if the front door is this messy, what does the code look like? Then they close the tab.
This guide gives you a structure that respects the reader’s time, a template you can copy, and the mistakes worth fixing in the README you already have.
The 60-second test
Before you publish a README, hand it to someone who has never seen your project — or imagine that reader honestly — and time them. In 60 seconds they should be able to answer:
- What does this project do?
- Is it for me, or for someone else?
- What do I type to see it working?
That is the whole test. Everything in this guide exists to help a stranger pass it.
The structure that works
You do not need every section below for a small project. But keep the order. Readers scan a README the way they scan a menu — appetizers of information first, deep detail later.
1. Name and one-line description
The first line after the title should be a single sentence a non-developer could repeat back to you.
Weak: “A robust, cutting-edge, enterprise-grade solution leveraging modern paradigms for invoice workflows.”
Strong: “Generates clean PDF invoices from a CSV file — built for freelancers who bill by the hour.”
Notice what the strong version does: it names the output (PDF invoices), the input (a CSV file), and the person (freelancers). If your one-liner cannot name all three, you probably do not yet know who the project is for — and that is worth fixing before the code, not after.
2. A screenshot, demo, or sample output
One picture of the thing working beats three paragraphs describing it. For a command-line tool, paste the actual terminal output. For a library, show the smallest possible code sample and what it returns. Keep it current — a screenshot from an old version quietly tells readers the project may be abandoned.
3. Quick Start
This is the most important section in the file, and the one most often broken. Three rules:
- List prerequisites first. “You will need Node.js 18 or later” in bold, before the commands — not discovered from an error message afterward.
- Give commands that can be copied exactly. No placeholders the reader has to guess at, no steps described in prose when a command exists.
- End with proof it worked. Tell the reader what they should see: “Open http://localhost:3000 and you should see the dashboard,” or “The terminal prints `Invoice #1042 created`.”
Example:
git clone https://github.com/example/acme-invoices.git
cd acme-invoices
npm install
npm startIf your real setup has more steps than that, that is fine — hiding them is not. A ten-step Quick Start that works is worth far more than a three-step one that doesn’t.
4. Usage, with real examples
Show the two or three things people will actually do most, using realistic inputs — not `foo`, `bar`, and `test123`. A freelancer reading your invoice tool understands `clients.csv` and `$85/hour` instantly. Generic placeholders force the reader to translate, and every translation is a place to give up.
5. Configuration
If your project uses environment variables or a config file, list every option in a small table: the name, what it does, and its default. The reader should never have to read your source code to learn that `INVOICE_CURRENCY` exists.
6. The remaining sections, in this order
- Project structure — a short tree or paragraph, only if the layout is not obvious.
- Running the tests — the exact command, nothing more.
- Contributing — how to open an issue and a pull request, or a link to a separate CONTRIBUTING file.
- License — name it and link to the LICENSE file. “Open source” without a license legally means all rights reserved, which is the opposite of what most authors intend.
A copy-and-paste README template
# Project Name
One sentence: what it does, from what input, for whom.
## Quick Start
**Prerequisite:** Node.js 18 or later.
git clone https://github.com/example/project.git
cd project
npm install
npm start
You should now see: [describe the expected result].
## Usage
[Example 1 — the most common task, with a real input and its output.]
[Example 2 — the second most common task.]
## Configuration
| Option | What it does | Default |
|---|---|---|
| EXAMPLE_OPTION | What it controls | its default |
## Running the Tests
npm test
## Contributing
Issues and pull requests are welcome. Please open an issue first
for anything larger than a small fix.
## License
MIT — see the LICENSE file.Do not ship the template unchanged. Every bracket in it is a decision you still need to make, and a reader can smell a template that was never filled in.
Five mistakes that make developers stop reading
1. The README describes the project you meant to build.
Features that are planned, half-finished, or removed do not belong in the present tense. If something is coming, put it in a clearly labeled Roadmap section — or leave it out entirely until it works.
2. The install steps were never tested from scratch.
This is the most common failure of all. Steps written from memory skip the dependency you installed globally six months ago and forgot about. Once per release, follow your own Quick Start in a clean environment — a fresh container, a new machine, a virtual environment you have never touched. Ten minutes of this finds more README bugs than a month of proofreading.
3. A wall of badges.
Twenty shields at the top — build status, coverage, version, downloads, license, three chat links — push the actual description off the screen. Keep the license badge and the build status. Delete the rest without guilt.
4. No license, or a license mentioned only in passing.
Companies cannot adopt unlicensed code, and careful developers will not either. Choosing a license takes five minutes and removes a permanent barrier to every serious user.
5. The README and the project drifted apart.
A README that describes version 1 while the code is on version 3 is worse than a short README, because it teaches readers not to trust anything in it. Treat a README update as part of every feature change, the same way you would treat a test. Our companion guide on improving your documentation workflow goes deeper on building that habit across a whole project.
How long should a README be?
As long as the 60-second test plus an honest Quick Start require — and not much longer. For a small utility, that might be 40 lines. For a framework, it might be 400, with the details moved into a docs folder or website that the README links to. The README’s job is not to document everything. Its job is to get the right reader started and point them to the right place for everything else.
Length is not the sin. Order is. A long README with the Quick Start at the top works fine. A short README that opens with legal text and a contributor list fails anyway.
Frequently asked questions
Should a README be written in Markdown?
Yes, in almost every case. A `README.md` renders automatically on GitHub, GitLab, and similar platforms, supports code blocks and tables, and stays readable as plain text. That combination is hard to beat.
What is the difference between a README and project documentation?
The README is the front door: what it is, how to run it, where to go next. Documentation is the rest of the house: full API references, tutorials, architecture notes, and troubleshooting guides. Most projects need a good README long before they need a documentation site.
Does a private or internal project need a README?
Yes — arguably more than a public one. Six months from now, the new hire and the future version of you are both strangers to this codebase. Write the README for them, and include the things only your team knows: how to get credentials, who owns what, and where it is deployed.
How often should I update my README?
Whenever setup, requirements, or core usage change — which in practice means reviewing it at every release. If a step in the Quick Start no longer works, that is a bug with the same priority as a bug in the code.
Bottom line
A README is not a formality you complete after the real work. For most readers, it is the project — the only part they will ever judge you by. One honest sentence about who it serves, a Quick Start you have personally tested from a clean slate, and one real example will put your README ahead of most projects on the internet. Start there, keep it true, and let it grow only when readers actually need more.
1 thought on “How to Write a README File That Developers Actually Read”