DEV Community

Cover image for Encourage Community with a Good ReadMe
Christina Gorton for Scarf

Posted on

Encourage Community with a Good ReadMe

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
Haystack logo and project description

Jina by Jina AI
Jina's logo and project description

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.

Forem's repository table of contents

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.

Fluent-bit's quick start guide

Grouparoo 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

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.

Kestra's demo app available at https://demo.kestra.io/ui/

Httpie includes several different examples of their HTTP client including a gif to help visualize.

Httpie example animation

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.

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.

Plausible's contributor section with contributor images displayed.

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

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.

Discussion (0)