Encourage Community with a Good ReadMe
Tags: opensource, github
Published: 2022-06-02 16:28:53

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](https://github.com/deepset-ai/haystack) by Deepset AI
![Haystack logo and project description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/92chtws00c3870kzare2.png)

[Jina](https://github.com/jina-ai/jina#readme) by Jina AI
![Jina's logo and project description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/bypzh392tav7cdk7f0br.png)

### 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](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).  

To automatically generate a TOC, you can use an online tool like the [GitHub Wiki TOC generator](https://ecotrust-canada.github.io/markdown-toc/). I used this tool to create the TOC in Forem’s [Selfhost](https://github.com/forem/selfhost) project when I was a developer advocate there. 

Their open source project, [Forem](https://github.com/forem/forem#table-of-contents), is another good example of a project that uses a TOC to help their community navigate the many sections of their ReadMe.

![Forem's repository table of contents](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yknf6qcj11wmnary1ty4.png)

### 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](https://github.com/fluent/fluent-bit) is on example of a project that has a quick start section and links out to more detailed build and install instructions.

![Fluent-bit's quick start guide](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hrsf4szrmwozt3xjbvbn.png)

[Grouparoo](https://github.com/grouparoo/grouparoo#running-a-grouparoo-application) is another good example of including a quick reference to running their application, but also linking out to a fuller version. 

![Grouparoo's installation guide to run their application](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/v5g16rosfav7maogfgk6.png)

### Usage Examples

Usage examples help your community visualize how your project can be implemented and better explains your project’s use cases. 

[Kestra](https://github.com/kestra-io/kestra#demo) includes a demo app users can play within their ReadMe.

![Kestra's demo app available at https://demo.kestra.io/ui/](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/em4s6wfn36alpdlomtyk.png)

[Httpie](https://github.com/httpie/httpie#examples) includes several different examples of their HTTP client, including a GIF to help visualize.
 
![Httpie example animation](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2tpkea68hncc9yoqp6xm.gif)

### 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](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository)
- [The Legal Side of Open Source](https://opensource.guide/legal/)
- The Linux Foundation: [Open Source Licensing Basics for Software Developers (LFC191)](https://training.linuxfoundation.org/training/open-source-licensing-basics-for-software-developers/)

### 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](https://contrib.rocks/preview) or [Open Collective](https://remarkablemark.org/blog/2019/10/17/github-contributors-readme/) to generate a contributors list and display an image on their ReadMe.

![Plausible's contributor section with contributor images displayed.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/o4omk4g23sdh6j0edacb.png)

### 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. 
![Github's Insights tab and community standards](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/93cujiza9kp18r1t70qv.png)

This tab provides a checklist you can follow to your community the best experience with your project. Try to include:

- [A contributing guide](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors)
- [A code of conduct](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project)
- [Issue templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/manually-creating-a-single-issue-template-for-your-repository)
- [PR Templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository)

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.