What sections a good README needs
A README is the front door of a repository. Most visitors read the first screen and leave, so the order of sections matters as much as their content. This page sets out a structure that answers the reader’s questions in the order they ask them.
The questions a visitor asks, in order
- What is this?
- Is it for me?
- How do I try it right now?
- How do I do the thing I came for?
- How do I change it, report a bug or help?
- Am I allowed to use it?
A strong README puts one section against each question and keeps them in that order. Anything that answers none of them, such as a long history of the project, belongs further down or in another file.
The core sections
| Section | Answers | Length to aim for |
|---|---|---|
| Title and one-line summary | What is this? | One sentence |
| Why / features | Is it for me? | Three to six bullets |
| Quick start | How do I try it? | Install plus one runnable command |
| Usage | How do I do my task? | Two or three common cases with code |
| Configuration | What can I change? | A table of options and defaults |
| Contributing | How do I help? | A short paragraph or a link to a guide |
| Licence | Can I use it? | One line naming the licence |
Optional sections and when they earn a place
- Requirements. Add it when the project needs a specific runtime version, a database or an operating system.
- Table of contents. Useful once the file is long enough to need scrolling more than a few screens.
- FAQ or troubleshooting. Add it when the same issue is reported more than once.
- Screenshots. Worth it for anything visual; a picture of the result answers “is it for me?” faster than words.
- Roadmap. Only if it is kept current; a stale plan misleads.
- Acknowledgements. For credit to projects you build on.
A fill-in outline
# project-name
One sentence: what it does and for whom.
## Features
- ...
- ...
## Quick start
install command
run command
## Usage
Short explanation, then a code example per common task.
## Configuration
| Option | Default | Description |
|--------|---------|-------------|
## Contributing
How to set up a dev copy, run tests and send changes.
## Licence
Name of the licence (see LICENSE).
Where else information should live
A README that tries to hold everything becomes hard to scan. Move material out when it has its own audience:
| Content | Better home |
|---|---|
| Release history | CHANGELOG.md |
| Detailed contribution rules | CONTRIBUTING.md |
| How to report a vulnerability | SECURITY.md |
| Full API reference | A docs/ folder or generated site |
| Licence text | LICENSE |
Code hosts recognise several of these file names and link them from the repository page, so readers find them without being told.
Structural mistakes
- Burying the quick start. If install instructions appear after a long background story, many readers never reach them.
- A summary that names the stack, not the job. “A React and Node app” says how, not what. Lead with the problem it solves.
- Headings with no content. An empty “Usage” section is worse than none; it signals the project is unfinished.
- Drift. Commands that no longer work. Re-run the quick start whenever you change setup steps.
Questions
Does a private internal project need a README?
Yes, arguably more. The next reader is often you, months later, without the context you have today.
Should the README explain the architecture?
A short overview helps contributors. Keep deep design notes in docs/ and link to them.