README best practices

Don’t spend 2 hours on your next project’s README

The quality of README decides the fate of a project because it’s the first impression it gives. Among the projects I have worked on and seen, most of the READMEs are excessive and confusing. As READMEs can come in many flavors, its best practices is a less discussed topic. Today I came across a well-written README template while browsing trending GitHub repositories, so I decided to post a blog on why I think this template makes perfect sense.

All the code/templates used in this post come from scottydocs@GitHub’s awesome repository:

scottydocs/README-template.md

I strongly recommend checking it out.

The purpose of a README is to answer 4 questions:

1. What is this project trying to achieve? (A short description will be great.)
2. Can I use it? (What are the prerequisites?)
3. If so, how? (How can I install it? What are the code snippets that work out-of-box?)
4. If I like it, how can I join? (What license is this project under? What are the rules for contributing?)

in the shortest amount of time possible.

Make project description short…