How to write a good README (a structure that works)
Visitors decide in about ten seconds whether your project is for them. Answer these questions in this order and most of your readers are served.
What is it? One sentence under the title, under about 120 characters. Name the thing and the audience: "Query JSON files from the command line with plain SQL."
Why use it? Three to five bullets phrased as outcomes, not implementation details.
How do I run it? Install and one working command, copy-pasteable, with prerequisites (language version, OS).
What does it look like? A real example with real output, or a screenshot or terminal GIF.
How do I configure it? Only the options people actually need; link to full docs for the rest.
How do I help or get help? Link the issues page, say how to contribute.
License. One line. Without it, many companies cannot legally use your code.
Template
# project-name
One sentence: what it does and for whom.
## Features
- outcome one
- outcome two
## Quick start
(install command)
(first command)
## Usage
(example input and output)
## Contributing
Issues and pull requests welcome: (link)
## License
MIT
Common mistakes
Starting with badges and a table of contents instead of what the project does.
Install steps that skip prerequisites.
Examples with no output shown.
No license, or no way to report a bug.
Describing how it is built before saying what it does.
Want to see how your own README stacks up? Use the free README score checker (runs in your browser).