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 and to the point

As suggested by scottydocs@GitHub, the project description should clearly state what the project does within 3 sentences.

The template by scottydocs@GitHub:

<project_name> is a <utility/tool/feature> that allows <insert_target_audience> to do <action/task_it_does>.

It is also used in many successful projects:

TensorFlow makes it easy for beginners and experts to create machine learning models. See the sections below to get started. (from Tensorflow homepage)

An open source machine learning framework that accelerates the path from research prototyping to production deployment. (from PyTorch homepage)

Kubernetes is an open-source system for automating deployment, scaling, and management of containerized applications. (from Kubernetes homepage)