A good README.md is crucial for any open source project. They are living documents that need to be kept up to date as the project matures and changes.
Bare Minimum
At the bare minimum, a readme should have:
- Title and One Sentence Overview of the project
- Setup (How to Setup)
- Contributing (How to Contribute)
- License
- Contact
Getting Better
When I think of good a good readme, I think of a readme that has:
- A purpose and overview for the project with some photos! (including where to learn more about the project)
- How to develop and work on the project (development guides)
- How to set up and run the project
- The requirements for running the project
- What the project is built with (eg. Rails, React, Mysql)
- Contributing guidelines
- Security
- The team and developers
- The Copyright License
- (Dedication, optional)
Examples
Some good examples of decent readmes come from most major projects including:
- TensorFlow - Somewhat Barebones: Gives the overview, setup, how to contribute, and guides at the bottom
- Dependabot - Provides a Medium Sized Readme
- Discourse - Provides almost a full length feature of the project and good documentation