Sections of a great README:
Introduction
Explain in 1-2 sentences what your project does and why someone should care.
There’s a direct correlation between how easy it is to use the project and how many people are using it, so provide a quickstart demo:
Badges
Badges provide metadata and signals that can help someone decide whether to use your project or not. Include info like:
- Build
- Code coverage
- Dependencies
- Size
- Downloads
- Social (e.g., GitHub stars)
- Version
- Activity (e.g., last commit)
See Badgen, Shields.io, and Naereen/badges.
Prerequisites
Bring up prerequisites before a user installs the project. If a CLI or binary is required, provide a link to the download page.
Install
Describe the steps to install your project. If your project can be installed with a package manager, add a code block with the install command. If your project has additional build steps, cover them and explain edge cases for specific platforms or operating systems.
Usage
Explain how to run the project. This is a good place to describe what each script, class, function, or option does. Additional examples may be beneficial.
Release
Provide instructions on how to release, publish, and deploy the project. Note whether the process is manual or automated and how versioning works.
Security
Provide instructions on how to contact the project maintainer if a security vulnerability is found. This is important because if your project is open sourced, creating an issue will bring awareness to the bug, which puts more pressure on getting a fix out. See adding a security policy to your repository.
License
It’s good practice to state the project license in the README.
Addendum
CONTRIBUTING.mdhelps users understand how to contribute and make changes to your project (see template).- [
CODE_OF_CONDUCT.md] helps users understand how to conduct interactions with the project (see GitHub Docs). - If there are a lot of headings, include a table of contents at the beginning.
- “3 tips to be a better writer”