You add every section a tutorial recommends. Now the README scrolls for two minutes, the install command is somewhere in the middle, and people still open issues asking how to install it. The problem is not what is missing. It is what you kept.
How to Write a Good README: Start by Deleting
A README has one job — get a stranger from curious to running your project. Everything that does not serve that belongs somewhere else.
Most guides give you a checklist of twelve sections. Follow it and you produce a file nobody finishes reading.
Four things earn their place near the top: what it does, how to install it, one usage example, and the licence. Everything else has to argue for itself.
Need the structure built for you? Our GitHub README generator assembles the standard sections so you can focus on cutting.
What to Include in a README, and What to Move Out
The test: would someone deciding whether to use this read it right now?
| Content | Where it goes |
|---|---|
| What the project does | README, first line |
| Install command | README, above the fold |
| One usage example | README |
| Licence | README plus a LICENSE file |
| Full API reference | docs/ — link to it |
| Contributing guidelines | CONTRIBUTING.md |
| Code of conduct | CODE_OF_CONDUCT.md |
| Changelog | CHANGELOG.md or releases |
| Roadmap | Issues or a project board |
Those last five are not less important. They just serve a different reader at a different moment, and GitHub links several of them automatically once the files exist.
Contributing guidelines are the clearest example. Put them in CONTRIBUTING.md and GitHub surfaces them on the issue and pull request screens — exactly where a contributor is standing.
The README Structure That Works
Six blocks, in this order.
- Title and one sentence. What it does, in plain words.
- Badges. Three or four. Licence, version, build.
- A screenshot or GIF, if there is anything to see.
- Install. The literal command, in a code block.
- Usage. One realistic example, not a toy one.
- Licence and links. Short, at the bottom.
Notice what is not in that list: a table of contents. GitHub now generates an outline from your headings with a built-in button, so a hand-written list is duplicated work that goes stale within two releases.
In our experience the ordering matters more than the content. An install command below three badges rows and a philosophy section may as well not exist.
Write the First Sentence for a Stranger
This is the line that decides whether anyone reads the second one.
The most common failure is assuming context. You know what problem the project solves, so you skip straight to how it works.
Compare these:
- "A zero-config, plugin-based transformer with a streaming API."
- "Converts CSV files to JSON, including files too large to fit in memory."
The second one tells a stranger whether to keep reading. The first describes the implementation to someone who already decided.
One more line almost nobody writes: what the project deliberately does not do. In a crowded space that saves you support questions and helps the right people self-select.
README Best Practices for Things That Rot
Most of a stale README is stale for the same three reasons.
- Version numbers in prose. "Requires Node 16" is wrong within a year. Point at package.json instead.
- Roadmaps. A list of planned features reads as abandoned the moment it stops moving.
- Relative image paths. They work in the repo and break everywhere the README is mirrored — npm, PyPI, package aggregators.
That last one catches everyone once. Use the full raw.githubusercontent.com URL for any image you want to survive off GitHub.
Live badges are the honourable exception to the version rule, since they read the real number. Our badge generator builds the ones that update themselves.
Show It, Do Not Describe It
A code block beats three paragraphs. A GIF beats both.
For a library, the usage example should be code someone could paste and run. Toy examples with foo and bar teach nothing about whether the API is pleasant.
For anything with an interface, put a screenshot or a short GIF near the top. It answers "is this what I think it is" in about two seconds.
The caveat: keep it small. We have seen 12 MB GIFs make a repository page take five seconds to render, which costs more than the demo gains.
Setting up a new repository? A a .gitignore file is the other file worth getting right on day one.
Wrapping Up
Knowing how to write a good README is mostly knowing what to leave out. Four things near the top, everything else in its own file with a link.
Write the first sentence for someone who has never heard of your project, put the install command above the fold, and delete anything containing a version number.
For starting points by project type, see our open source README template collection.