How to improve your GitHub README: a practical guide with before-and-after examples
By Bright Oparaji9 min read
A README has two readers: the stranger deciding in a few seconds whether to stay, and the user who stayed and now needs to get something working. A good one serves both, in that order.
Your README is the page every link to your project lands on. People arriving from a post, a search or a recommendation read it before they read any code, and most of them decide quickly. This guide goes through what a project README needs, section by section, with a before-and-after example and a checklist you can reuse.
To check your own as you go, paste it into the README quality checker. It scores the README from 0 to 100 against a published rubric and lists the fixes worth the most first. For the first screen specifically, our earlier piece on what a README has to do in its first ten seconds goes into more depth.
What the data says is usually missing
We measured 2,069 public GitHub READMEs for the README Benchmark. The gaps are consistent. About six in ten have installation instructions. About a third name their licence in the README. Fewer than a quarter have a feature list. And around nine in ten never say who the project is for.
Some elements are much more common among larger projects. In the benchmark, a link to documentation appears in 11% of READMEs in the smallest star band and 76% in the largest; contributing guidance goes from 12% to 65%; a screenshot or other non-badge image from 20% to 61%. That is a correlation, not proof that adding them causes growth. It does show what readers of established projects have come to expect.
The sections, in order
1. A clear introduction
Under the title, one or two sentences saying what the project is and what problem it solves. Put it before badges, logos and tables of contents, because it is what the reader is looking for.
Write it for someone who has never heard of the project. Name the category ("a command-line tool", "a Python library") and the job it does.
2. The value proposition
Say why someone would choose this over the alternative they already use. One specific difference beats a list of adjectives. "Uses 10 MB of memory where the usual approach needs 200 MB, measured on the benchmark in /bench" can be checked. "Lightweight and blazing fast" cannot.
3. Who it is for
A short line or section naming the intended user and situation. It is the most commonly missing element, and it saves time for everyone: the right readers recognise themselves, and the wrong ones leave early instead of opening an issue later.
It helps to say who it is not for, too: "Not suitable for projects that generate class names at runtime."
4. Key features
Three to six bullets, each something a reader can verify. Lead with what matters most to the audience from section 3.
5. Requirements and dependencies
What must already be installed, with versions: language runtime, database, operating system, hardware. A failed first install is very often a missing prerequisite the README did not mention.
6. Installation
The exact commands to copy, in a code block, for each way you distribute the project. Test them on a clean machine, or ask someone who has never installed it to follow them while you watch.
7. Quick start
The smallest example that runs and produces a visible result, directly after installation. A reader should be able to go from nothing to a working result in a few minutes.
8. Usage documentation
Short examples of the two or three most common tasks, then a link to fuller documentation. The README is the entry point, not the whole manual; long API references belong in a docs site or a docs folder.
9. Screenshots and demos
Show the project working: a screenshot, a short recording, terminal output, or a before-and-after code sample for a library. Give every image alt text describing what it shows. Badges are not a demonstration.
10. Contributing
A short section, or a link to CONTRIBUTING.md, explaining how to set up a development copy, run the tests, and what kind of contributions are welcome. Link issues labelled for newcomers if you have them.
11. Licence
Name the licence in a short section and link the LICENSE file. Many developers and most companies check this before anything else.
12. Support and links
Where to ask questions, where to report bugs, where to report security issues, and links to documentation, a demo or a website. A reader with a question should not have to guess where it goes.
13. Calls to action
Tell the reader what to do next: try the quick start, read the documentation, join the discussion, pick up a first issue. One or two clear next steps beat a wall of badges.
14. Accessibility and readability
- Use one top-level heading for the project name and level-two headings for sections, in order, so screen readers and generated tables of contents work.
- Give images alt text.
- Keep paragraphs short and use lists for steps.
- Do not rely on colour or emoji alone to carry meaning.
- Write link text that makes sense out of context ("installation guide", not "click here").
Before and after
Here is a README of the kind we see often:
# fastcss


The best CSS tool. Fast, simple, powerful.
## Usage
Run it on your project.
A reader cannot tell what it does, whether it is for them, how to install it or what using it looks like. Here is the same project after applying the sections above:
# fastcss
fastcss finds CSS selectors that are never used in your built site and
tells you which ones are safe to delete.
It is for teams shipping static or server-rendered sites who want smaller
stylesheets without breaking pages. It is not suitable for apps that build
class names at runtime.

## Features
- Scans built HTML and CSS, so it sees what actually ships
- Reports unused selectors with the file and line they come from
- Safe mode lists candidates without changing any file
## Requirements
Node.js 20 or later.
## Installation
```bash
npm install --save-dev fastcss
```
## Quick start
```bash
npx fastcss ./dist
```
Prints each unused selector and the total size you would save.
## Documentation
Full options and CI setup: [docs/README.md](docs/README.md)
## Contributing
Bug reports and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md)
to set up a development copy. Issues labelled "good first issue" are a good
place to start.
## Support
Questions go to [GitHub Discussions](https://github.com/example/fastcss/discussions).
Report security issues privately as described in [SECURITY.md](SECURITY.md).
## License
MIT. See [LICENSE](LICENSE).
The project is invented for the example, but every change is one you can make to a real README: an opening sentence that explains, a line naming the audience and the exceptions, a real image, verifiable features, requirements, installation, a quick start, and clear places to go next.
Common mistakes and how to fix them
| Mistake | Why it costs readers | Fix |
|---|---|---|
| Badges and logos before any explanation | The reader scrolls past decoration looking for what the project is | Move the one-sentence description directly under the title |
| Slogans instead of a description | "Fast, simple, powerful" cannot be checked | Say what it does, for whom, in plain words |
| No installation commands | Readers guess, fail and leave | Add copyable commands in a code block, tested on a clean machine |
| Installation but no example | Readers do not know what using it looks like | Add a minimal quick start after installation |
| Assuming knowledge | New users miss steps the author no longer notices | Have someone new follow the README and note where they stop |
| The README is the whole manual | Important parts are buried | Keep the essentials and link to fuller docs |
| Outdated instructions | Commands that no longer work destroy trust quickly | Review the README with every release |
| Images without alt text | Screen reader users miss the content | Describe what each image shows |
| No licence named | Companies and careful developers cannot use it | Add a short License section |
| No way to ask questions | Questions arrive as issues, or not at all | Link Discussions, a forum or a chat |
Reusable README checklist
- One sentence under the title says what the project is and the problem it solves
- The intended user is named, and who it is not for if that helps
- One specific, checkable difference from the usual alternative
- Three to six verifiable features
- Requirements listed, with versions
- Installation commands in a code block, tested from scratch
- A quick start that produces a visible result
- Examples of the most common tasks, and a link to full documentation
- A screenshot, recording or sample output, with alt text
- A contributing section or a link to CONTRIBUTING.md
- The licence named in the README
- Where to ask questions and report security issues
- One clear next step for the reader
- One top-level heading and ordered section headings
Check yours
Paste your README, or name its public repository, in the README quality checker. It shows a score by category, what is missing, and the changes worth the most points first, with examples. When it is ready, the open-source launch planner helps you decide where to share it, and our 12-step launch checklist covers what comes after.