How to Create the Perfect README for Your Open Source Project
Tags: opensource, github, beginners, webdev
Published: 2021-11-02 19:31:24

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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5t4kaw5iwq8yha4kj3g3.png)
_This example is sourced from [Open Sauced](https://github.com/open-sauced/open-sauced)_

### Add a few short statements describing why your project exists and what it does
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1jz81nmvoiwig6ul0awc.png)
 _This example is sourced from [Slinkity](https://github.com/slinkity/slinkity)_

### Inform users on how to install and use your project
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8i2hp7jht3pxn4vnn6ak.png)
 
 _This example is sourced from [Timber](https://github.com/timber/timber)_

### Let users know how they can get help
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/e5kzvxroet9e6szxk8fm.png)
 _This example is sourced from [RasaHQ](https://github.com/RasaHQ/rasa)_

### Include links to essential documentation
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/v0w64s7nnoz5nf9sxhy9.png)
 _This example is sourced from [CodeNameOne](https://github.com/codenameone/codenameone)_

### Show off your contributors
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xh1tar6yb8oisib37anb.png)
_This example is sourced from [use-shopping-cart](https://github.com/dayhaysoos/use-shopping-cart)_

### Add a link to your project's license 
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ca92a90n3fp47l6l7if7.png)
 _This example is sourced from [RasaHQ](https://github.com/RasaHQ/rasa)_

### Go the extra mile by adding:
- A Table of Contents
    - (Here’s a [doc](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes#auto-generated-table-of-contents-for-readme-files) 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](Readme.so), an open source project built by [Katherine Peterson](https://github.com/octokatherine) makes it easy to build and customize all the sections of your README.

You can also use this [template](https://github.com/cfpb/open-source-project-template/blob/main/README.md) provided by the Consumer Financial Protection Bureau.

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