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
 
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
 
johanneslichtenberger profile image
Johannes Lichtenberger

Thanks, great post and really helpful :-)

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
 
sndp487 profile image
Sandeep

Here's a readme that I made recently.

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

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
 
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
 
pratikaambani profile image
Pratik Ambani

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

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

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
 
aweysahmed profile image
Aweys Ahmed

Great post. Thanks for sharing.

Collapse
 
houarizegai profile image
Houari ZEGAI

Great post, thanks.

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!