DEV Community

Cover image for How to write a perfect README for your GitHub project

How to write a perfect README for your GitHub project

Marc Seitz on June 26, 2023

What you will find in this article? You've probably stumbled upon many GitHub repositories, each with their own unique README page. Have...
Collapse
 
elijahtrillionz profile image
Elijah Trillionz

Really nice, clear article.
It is unfortunate that not all ReadMes are as clear as they should. This is a really good article for any open-source developer to familiarize with.
Thanks for sharing

Collapse
 
mfts profile image
Marc Seitz

Thank you Elijah 🙌 This README is most suited for an "application" type project. There are so many other projects like libraries, packages, non-code projects that require some different README content.

Collapse
 
elijahtrillionz profile image
Elijah Trillionz

Most def, but this is like a foundation for all to me.
My library actually includes most of the things you mentioned here and many other principles.

Thread Thread
 
mfts profile image
Marc Seitz

That's fantastic 🤩

Collapse
 
sumitsaurabh927 profile image
Sumit Saurabh

Very well-written article Marc.

Does one thing and does it well. Loved reading it!

Collapse
 
mfts profile image
Marc Seitz

Thanks Sumit! Sometimes simple way is the best way

Collapse
 
sumitsaurabh927 profile image
Sumit Saurabh

'The ultimate sophistication' for a reason!

Collapse
 
derlin profile image
Lucy Linder

I find a TOC (table of content) very useful as well.

A good tool is bitdowntoc

Collapse
 
mfts profile image
Marc Seitz

Yes absolutely. Table of contents are underrated. Even though GitHub auto-generates it based on the headers, I never open them. When they are embedded in the README it's 100x more useful.

Collapse
 
kurealnum profile image
Oscar

Definitely going back and rewriting some of my README's now! This is really slick.

Collapse
 
mfts profile image
Marc Seitz

Thank you Oscar! Definitely let me know how it turns out. I'm always interested to learn from others

Collapse
 
shnai0 profile image
Iuliia Shnai

Need to update mine now

Collapse
 
mfts profile image
Marc Seitz

Go Go Go! It's never been easier. Also check out readme.so

Collapse
 
subhmsft profile image
Subhasish G

Excellent post. Loved the concept of gifs. Need to tinker with a few README pages that I have in my own repos; need some improvement.

Collapse
 
mfts profile image
Marc Seitz

Oh gifs in the README are a gamechanger. Makes it really interactive and catchy for people to understand the most valuable aspect of your project.