Awesome README: A Template for Writing Useful READMEs

You can skip to the template here.

People can’t use what they don’t understand.

For open source projects, good documentation is as important as the project itself.

This is a guide to create useful READMEs that is best suited for small open source projects without dedicated websites having extensive documentation.

You can use this guide as a reference and build on top of it for your projects.

A Useful README

A README file is the first thing a user will see in your project. First impressions last, so it is important to make a good README.

A good README also helps:

• your project cut through the noise and stand out
• your users understand how to use the project
• your contributors contribute to the project

There is not a one-size-fits-all when it comes to usability. But having the following sections can help:

1. Title and description: Name of your project and an introduction to what it is about.
2. Quickstart/Demo: A short introduction that users can follow to get started quickly with your project.
3. Installation: A guide on how users can install your project.
4. Usage: Details on how to use the project.
5. Development: How users can build a development version of the project on their machines.
6. Contribute: Guide for open source contributors looking to contribute to the project.

Considering all these, I have created a reusable template you can fork on GitHub.

Depending on your project, you might have very different README files. The idea is to use this as a reference as you write your README.