README Love: Quick and Easy Tips

READMEs are AWESOME. They are one of the best things you can add to a repository, (other than quality code), to make it look professional.

What Makes a README Great?

Directions on how to clone or fork the repo and run it locally.
Explain it like you’re explaining things to a totally new programmer. Try not to make assumptions.

Directions on how to run the test suite.

Directions on how to seed the database (if relevant).

A link to the production site.

A screenshot (or a few) of what the app does.
This is especially important if you don’t have the production app up and running yet or it’s a side project and you’re hosting on Heroku. Heroku gets sleepy, so you could lose a potential employer’s interest in your pet project during the time it takes for Heroku to wake up.

Directions on How to Contribute to the Project

After reading the first draft of this blog, my co-worker Laura suggested:

“One more thing I see a lot in READMEs for open source is “how to contribute”. Having some encouraging words or guidelines can be nice if you’re interested in helping out.”

As projects grow, good READMEs are vital for on-boarding new developers and enticing open source contributions.

And for new developers, READMEs help give a side project a professional look and feel to potential future employers.

You never know when someone you want to work for will be looking at your Github, so make your repos looks great.

Some Basic Examples

Etsy-Gem has a good small README
– Jekyll – You don’t have to cram all the documentation in one file, check out the Jekyll repo!

 Markdown References

READMEs are usually written in Markdown – if you’re a little fuzzy on Markdown syntax, check out these references

Markdown Basics

Github Flavored Markdown

Get a good Markdown editor!
Not sure what’s hip now, but I’ve used Mou

Some Fancy README Tricks!

Did you know you can embed screenshot gifs in a README?!
Check out to record a gif of your screen.

You can make a RELATIVE link in a README
When does this come up?
If you’re working in a branch and add a hardcoded link in your README to something in the repo, when you merge back to master the image link will no longer work. Here are instructions

 README documentation can be overdone – but keeping a concise, well loved little (mostly) living document of your code will pay you back in dividends.