Sections of a great README:
The introduction should explain in 1-2 sentences what your project does and why the user should care.
Provide a quickstart example since there’s a direct correlation between how easy it is to use the project and how many people using it. Demos can be created using:
Badges provide metadata (and signals) that can help the user decide whether to use your project or not. Include information like:
- Code coverage
- Social (e.g., GitHub stars)
- Activity (e.g., last commit)
Bring up any prerequisites before the user installs the project. You don’t necessary how to detail the steps to install a common binary, but you can provide a link to the binary’s download page.
Describe how to install your project. If your project can be installed using a package manager, add a code block with the install command. If your project has additional build steps, cover them and explain any nuances (e.g., different platforms or operating systems).
Explain how to run and use the project. This is a good place to describe what each script, class, function, or option does. Further examples can also beneficial.
Provide instructions on how to contact the project maintainers if a security vulnerability is found. This is critical because if your project is open sourced, creating an issue will bring awareness to the bug, which puts more pressure in getting a fix out. See adding a security policy to your repository.
Even if there’s a separate
LICENSE file, it’s good practice to state the project license in the README.
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”