DEV Community

Cover image for How to Create the Perfect README for Your Open Source Project

How to Create the Perfect README for Your Open Source Project

Rizèl Scarlett on November 02, 2021

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 att...
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
 
atulcodex profile image
🚩 Atul Prajapati 🇮🇳

Nice tool but i think we need some UI improvements, what do you think?

Collapse
 
michaelcurrin profile image
Michael Currin

Yes it needs improvements. Can you give any specific suggestions?

Thread Thread
 
atulcodex profile image
🚩 Atul Prajapati 🇮🇳

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

Collapse
 
blackgirlbytes profile image
Rizèl Scarlett

I checked it out a little bit. Very cool.

Collapse
 
michaelcurrin profile image
Michael Currin • Edited

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

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

Collapse
 
michaelcurrin profile image
Michael Currin

Thanks. Fixed

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.

Collapse
 
natzar profile image
Beto

Good compilation! Used everyting.

Stripe Pad README file: github.com/natzar/Stripe-Pad/blob/...

Collapse
 
maitrungdong profile image
Mai Trung Đông

I got it. Thank you so much. 💯

Collapse
 
blackgirlbytes profile image
Rizèl Scarlett

No problem. Thanks for reading!