A great README gets people running your project in minutes. A simple structure, a five minute test and a template you can copy for your next repository.

Someone lands on your repository. In about thirty seconds they decide whether it is useful, and whether it is worth the effort to try. The README is nearly all they have to go on.

Most weak READMEs are not badly written. They simply answer the wrong questions, or skip the basics because the author knows them too well.

The questions a visitor has

Answer them in this order and your README does its job.

A structure you can copy

README.md
# Project name

One sentence on what it does and who it is for.

## Why
The problem this solves, in two or three lines.

## Quick start
    npm install projectname
    npx projectname init

## Usage
The most common example, with the expected output.

## Configuration
A table of options and their defaults.

## Contributing
How to set up a dev environment and run the tests.

## License
Name the license and link to the LICENSE file.

The top matters most

Write the first sentence so that a stranger understands what the project is. Avoid insider words. Compare these:

The first line decides whether people keep reading.

After the opening, show a screenshot, a short animation or a three line code example. Seeing the result is more convincing than any description.

Make the quick start actually quick

  • List prerequisites, with versions: “Node 20 or newer”.
  • Give commands that can be copied and pasted without editing.
  • Show what success looks like, for example the output after the first run.
  • Mention the most common failure and its fix.

Keep it alive

  • Update the README in the same pull request that changes behavior.
  • Test your code examples now and then, or run them in CI.
  • Link to longer documentation rather than stuffing everything in one file.
  • Remove sections that are out of date. A missing section is better than a wrong one.