How to write a good README

Do not index

A README is the first file most people open in a project. Its job is to get a new reader from "what is this?" to a working setup as fast as possible, and to tell them where to look next.

Start with one paragraph

Say what the project does, who it's for, and what problem it solves, in plain words. If someone reads only this paragraph, they should know whether the project is relevant to them.

Show how to install and run it

Give the exact commands, in order, and say what the reader should see when each one works.

git clone https://github.com/example/project.git
cd project
npm install
npm start

If a step needs something installed first, such as a specific runtime version or a database, say so before the step, not after it fails.

Give one real example

One short example of the project doing its main job is worth more than a list of features. Show the input and the output.

Explain the layout

A few lines on where things live save a newcomer a lot of searching:

where the source code is,

where the tests are and how to run them,

where configuration lives.

Say how to get help and contribute

Link the issue tracker, say how you'd like changes proposed, and name the license.

Keep it current

A README that describes last year's setup is worse than a short one. When a command or a step changes, update the README in the same change.