DEV Community

Cover image for How to Create the Perfect README for Your Open Source Project
Rizèl Scarlett for GitHub

Posted on • Updated on

How to Create the Perfect README for Your Open Source Project

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

Include links to essential documentation

Image description
This example is sourced from CodeNameOne

Show off your contributors

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

Add a link to your project's license

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!

Discussion (8)

Collapse
michaelcurrin profile image
Michael Currin

I made this tool to make it easy to add a tag badge, template button, dependency badge, license section... to docs.

michaelcurrin.github.io/badge-gene...

For dependencies you can have something dynamic that references your live package.json

Or pick a premade badge from Catalogue page

Collapse
blackgirlbytes profile image
Rizèl Scarlett Author

I checked it out a little bit. Very cool.

Collapse
michaelcurrin profile image
Michael Currin • Edited on

Yes docs make a repo more professional and friendly, for other devs and for colleagues and potential employers.

I tried that tool before you recommended and found it needed too much manual changes for what I need.

I have this as a template across languages.

Docs directory

github.com/MichaelCurrin/generic-p...

Main README

github.com/MichaelCurrin/generic-p...


As a bonus, if you go from the repo main README you'll see a link to the docs site which is all markdown files and hosted with Jekyll and GH Pages.

Collapse
blackgirlbytes profile image
Rizèl Scarlett Author

Great share! The docs directory link is broken for me!

Collapse
michaelcurrin profile image
Michael Currin

Thanks. Fixed

Collapse
maitrungdong profile image
Mai Trung Đông

I got it. Thank you so much. 💯

Collapse
blackgirlbytes profile image
Rizèl Scarlett Author

No problem. Thanks for reading!

Collapse
qq449245884 profile image
qq449245884

Dear Rizel Scarlett,may I translate your all dev articles into Chinese?I would like to share it with more developers in China. I will give the original author and original source.