How to Create the Perfect README for Your Open Source Project

How to Create the Perfect README for Your Open Source Project
Rizel Scarlett's photo
Rizel Scarlett

Published on Nov 3, 2021

2 min read

Subscribe to my newsletter and never miss my upcoming articles

Hacktober is over, but that doesn't mean we shouldn't continue to encourage folks to contribute to open source. One of the ways maintainers can attract more long-term contributors is by writing a great README. I've done some research and compiled a list of tips for you to create a README that will attract contributors to your community.

Why should I create a README?

Creating a README for your personal profile and your organization is fun and essential. However, writing an excellent README for your open source project's repository is of equal importance. Your README provides new users and potential contributors with the first impression of your project. To be clear, while your Contributing.md enables contributors to make and merge pull requests in your repo, your README guides users on how to use your project.

What should I write in my README?

Start by adding the title for your project

Image description This example is sourced from Open Sauced

Add a few short statements describing why your project exists and what it does

Image description This example is sourced from Slinkity

Inform users on how to install and use your project

Image description

This example is sourced from Timber

Let users know how they can get help

Image description This example is sourced from RasaHQ

Image description This example is sourced from CodeNameOne

Show off your contributors

Image description This example is sourced from use-shopping-cart

Image description This example is sourced from RasaHQ

Go the extra mile by adding:

  • A Table of Contents
    • (Here’s a doc on auto generating a table of contents for your read me)
  • The project's tech stack and features
  • A link to your production instance
  • A screenshot of the project's user interface
  • Dependencies
  • Known issues

I need help making it look pretty!

Try using Readme.so, an open source project built by Katherine Peterson makes it easy to build and customize all the sections of your README.

You can also use this template provided by the Consumer Financial Protection Bureau.

Comment below with a project's README that you love or a README you created!

 
Share this