Community is important for the health of an open source project. During my time as an open source community manager and developer advocate, I have seen how a project’s ReadMe can help with discoverability and encourage community contributions when they are well written. I have also seen how projects can turn away users when they don’t take the time to create a good ReadMe.
What Makes a Good ReadMe?
When you are looking to promote your open source project and encourage developers to use it there are a few things your ReadMe could include.
Project Name and Description
First, a ReadMe should be succinct. More detailed documentation about your product or project can be moved to a separate page or website. A few things you can add at the beginning of your ReadMe are:
- Product name and logo if available
- A short description that can include:
- What your application does,
- Why you used the technologies you used
- Some of the challenges you faced and features you hope to implement in the future.
Examples of project’s that do this well are:
Haystack by Deepset AI
Jina by Jina AI
Table of Contents
If your ReadMe is long or contains several sections, a Table of Contents(TOC) is helpful.
There are several tools you can use to create a TOC in your GitHub ReadMe.
First, you can manually generate a TOC with Markdown. You can follow the markdown in this cheatsheet.
To automatically generate a TOC, you can use an online tool like the GitHub Wiki TOC generator. I used this tool to create the TOC in Forem’s Selfhost project when I was a developer advocate there.
Their open source project, Forem, is another good example of a project that uses a TOC to help their community navigate the many sections of their ReadMe.
Installation Guide
As mentioned previously, in-depth documentation should be added to a separate page, but most users appreciate a "Quick Start" or installation guide, so they can test the project quickly.
You will want to provide a quick step-by-step description of how to set up and run the development environment.
Fluent-bit is on example of a project that has a quick start section and links out to more detailed build and install instructions.
Grouparoo is another good example of including a quick reference to running their application, but also linking out to a fuller version.
Usage Examples
Usage examples help your community visualize how your project can be implemented and better explains your project’s use cases.
Kestra includes a demo app users can play within their ReadMe.
Httpie includes several different examples of their HTTP client, including a GIF to help visualize.
Contributor Guide
A contributor guide will encourage your community to participate in the health and maintenance of your project.
A contributor guide is useful for both maintainers and contributors. Guidelines support good pull-requests and issues and encourages good communication between contributors and maintainers, which saves everyone a lot of time and hassle.
Add a License
An open source license makes it easier for other people to contribute to your project. Depending on the license, it will also encourage or discourage the free use and distribution of your project. A public project is not free to use, distribute, modify, or contribute back to by default. You need to add a license to explicitly give others the right to do so.
For more information on open source licensing, see the following resources.
- Licensing a repository
- The Legal Side of Open Source
- The Linux Foundation: Open Source Licensing Basics for Software Developers (LFC191)
Nice to Haves
Credit Authors or Contributors
In addition to a contributor guide, a section giving credit to the authors of the project and/or highlighting project contributors shows your appreciation for your community by centering the work they have done.
One example of a project that highlights their contributors with a “Contributors” section is Plausible. They use a tool like contrib.rocks or Open Collective to generate a contributors list and display an image on their ReadMe.
Additional Things to Check
If the project will be open to the public, you should check the Insights tab in your repository to view the Community Standards.
This tab provides a checklist you can follow to your community the best experience with your project. Try to include:
Maintaining an open source project is both exciting and exhausting. A ReadMe isn’t always at the top of mind when a developer or team open sources their code. Yet, taking the time to craft a good ReadMe encourages community and the health of your project. It will also save you time in the future by answering users questions from the start. Not everything in this list is necessary for a ReadMe, but even the addition of a few of these items will make an impact on your project.
Top comments (0)