Making a Good README
Your README file contains a high level overview for people interested in using, contributing, or perusing your code.
- Overview - A brief description outlining what the project
- Table of Contents - You can link to the different sections below using
#followed by the lowercased and kebab-cased version of the header. e.g.
Table of Contents => #table-of-contents
- Description - A more detailed outline of the project. What does it do? Is there a high level list of features? If describing a project that has visual features, consider adding pictures or animations of the features and functionality in this section.
- Installation - How can another developer get your project up and running on their own? What dependencies are required? Are there environmental requirements? Be specific, and outline steps to take in order to get the project running.
- Usage - Further details on how the project is meant to be used may be helpful. For a library or framework, this section would outline how to use the library within another project. For a service that is meant to be used within a larger project architecture, instructions on how to integrate may be necessary.
Additionally, for some projects, additional information might make sense.
- Related Projects - Links to other repositories that are related to the current one. Are there partner projects? Is there a newer version of this project elsewhere?
- Team Members - Add the names of your team members. Describe roles on the team such as "Product Owner", "Scrum Master" and more.
- Contributing - If you'd like others to be able to contribute to your work, outline a process through which they can submit a request for changes to be incorporated. More specifically, outline the Git workflow for these contributors. Should they use a feature branching workflow? Should they rebase or merge? Should the fork the repository? What is the review process?
- Roadmap - What future enhancements are planned? What is the current status of the project? Is it being actively maintained?
- License - If open source, state how the project is licensed.
Last modified: 202212070107