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
This example is sourced from Open Sauced
Add a few short statements describing why your project exists and what it does
This example is sourced from Slinkity
Inform users on how to install and use your project
This example is sourced from Timber
Let users know how they can get help
This example is sourced from RasaHQ
Include links to essential documentation
This example is sourced from CodeNameOne
Show off your contributors
This example is sourced from use-shopping-cart
Add a link to your project's license
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!
Top comments (12)
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
Nice tool but i think we need some UI improvements, what do you think?
Yes it needs improvements. Can you give any specific suggestions?
I can't give you any specific suggestion, but you have to get some UI design ideas from Pinterest, themeforest market places.
Se this tool hoppscotch.io
I checked it out a little bit. Very cool.
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.
Great share! The docs directory link is broken for me!
Thanks. Fixed
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.
Good compilation! Used everyting.
Stripe Pad README file: github.com/natzar/Stripe-Pad/blob/...
I got it. Thank you so much. 💯
No problem. Thanks for reading!