Here are the top 5 rules for all repository readme’s
1. Tell me what the repository is for in plain English. Even better, give me a diagram on what it does and how it does it. I’m talking a paragraph, maybe two, three at the most with an overview of what the repository (…application, package, framework, helper…) does. If a diagram makes sense here (and it almost always does) include one.
2. Tell me how to install it. Give me a bullet list of instructions on what I’ll need to do to prepare my machine/application/whatever before I install it, and then tell me exactly how to install it. Keep it simple, I’m expecting less than 10 steps. More than 5 and I’ll probably start looking elsewhere.
3. Tell me how to get the repository working, and give me code examples. I’ll want to see how this integrates with whatever it is I am doing/want. Show me the inputs and outputs, show me how to fire up the class / function, show me how to use it how you expect it to be used.
4. Tell me how you expect me to create a new pull request for this repository. I want to help out, so you should make it as easy as possible for me to be able to write new tests, fix bugs and create enhancements. Again keep it simple.
5. Keep it up to date. This is the big one. Codebases change all the time, make sure the readme reflects the current codebase all the time. Seriously. Ten minutes spend updating the readme with the latest changes will save so many people hours of frustration (including yourself in two months time).