DEV Community

Cover image for How to Write an Awesome GitHub README

How to Write an Awesome GitHub README

Andrew Healey on April 14, 2019

I read through the earliest README I could find. Written in 1975 by William J. Earl at the CS department of UIC. The text is a little dry but also ...
Collapse
 
vepo profile image
Victor Osório • • Edited

I always add a Rational section just after the description. To explain the whys behind my code.

Collapse
 
healeycodes profile image
Andrew Healey •

That’s a really neat idea, Victor 👍

Collapse
 
brianjenkins94 profile image
Brian Jenkins •

Here's a couple of resources that I really liked when I was doing my own research on how to write a README:

Collapse
 
10secondsofcode profile image
Elango Sundar •

I have created a repository for awesome github profile aims to collect the all awesome beautiful READMEs profile and make your Profile look good & Inspire other's.

Collapse
 
johanneslichtenberger profile image
Johannes Lichtenberger •

Thanks, great post and really helpful :-)

Collapse
 
tuandm profile image
Tuan Duong •

Nice post, your favorite's README is the one I am using for my project: github.com/tuandm/laravue.

Collapse
 
svenefftinge profile image
Sven Efftinge •

Also a proper GitHub readme should have a Gitpod button, so contributors can skip the setup part.
See e.g. github.com/thepracticaldev/dev.to#...

Collapse
 
healeycodes profile image
Andrew Healey •

Gitpod is an awesome technology!

Collapse
 
daisp profile image
Danny Priymak •

Awesome stuff, thanks.

Collapse
 
aweysahmed profile image
Aweys Ahmed •

Great post. Thanks for sharing.

Collapse
 
cirosantilli profile image
Ciro Santilli •

Asciidoc README with table of contents is Nirvana: github.com/cirosantilli/linux-kern...

Collapse
 
healeycodes profile image
Andrew Healey •

Thanks for sharing. This looks amazing!

Collapse
 
sndp487 profile image
Sandeep •

Here's a readme that I made recently.

github.com/sndp487/share-it/blob/m...

Collapse
 
houarizegai profile image
Houari ZEGAI •

Great post, thanks.

Collapse
 
burdettelamar profile image
Burdette Lamar • • Edited

I would add: it's crucial to Keep Your Example Code Green .

Collapse
 
healeycodes profile image
Andrew Healey •

Yes! I’ve ran into this problem on a repository recently.

Collapse
 
pratikaambani profile image
Pratik Ambani •

Nice one!! You guys may wish to refer this one ;)

dev.to/pratikaambani/a-meaningful-...

Collapse
 
maybebored profile image
Mayuran •

I enjoyed reading this. It was satisfying to learn something while finding out about new tools I probably would have never found about any other way. Thank you 👏

Collapse
 
healeycodes profile image
Andrew Healey •

Thanks Mayuran!

Collapse
 
vuelancer profile image
Vuelancer •
  • I have created a markdown crash course on youtube!
  • youtube.com/watch?v=x0Boemw9teU
  • Additionally, I have added a demo for github new profile-level README feature!