Image Description
Writing a useful README
A README is often the first proper explanation somebody sees when they find your project.
It therefore has one important job: help them understand what on earth they have just found.
Start with what the project is
Give the name and a short explanation. Do not make the reader inspect twelve source files before discovering that your project is a weather application.
Explain how to get started
Include requirements, installation steps and a small usage example where appropriate.
Document the important bits
Useful sections might include configuration, keyboard commands, accessibility information, supported platforms, building from source, contributing and troubleshooting.
State the licence
Tell readers how the project is licensed and normally include the full licence in an appropriate licence file.
Keep it current
An inaccurate README is worse than a short one. When setup instructions change, update them as part of the change rather than promising yourself you will remember later. Future you has enough problems.
Do not turn it into a novel
If documentation becomes large, give it a proper home and use the README to point people there. The README should help somebody get oriented quickly.
Answer the obvious questions first
A useful README should let somebody work out, fairly quickly, what the project is, whether it is relevant to them and how to get started.
If I have to scroll through three badges, an enormous logo and the complete history of the project before discovering what the program does, the README has got a little distracted.
A sensible order
For many projects, something like this works well:
- What the project is.
- Important requirements.
- How to install or run it.
- A small example.
- Where the full documentation lives.
- How to report bugs or contribute, if relevant.
- The licence.
That is not a law. Move things around when your project needs something different.
Keep examples small
If somebody needs a 70-line example before they can understand the basic idea, that example probably belongs in the documentation.
A README is the front door. It does not need to contain every room in the house.
Want a starting template?
I've made two deliberately simple ones:
Copy one, delete the bits you don't need and make it fit your project. The point of a template is to get you past the blank page, not to make every README sound identical.
Further reading and external resources
Want to dig into this a bit more? These are good places to go next. If anything here ever disagrees with the official documentation, trust the official documentation.