Skip to content

Instantly share code, notes, and snippets.

@hectorhuertas
Forked from rrgayhart/readmelove.md
Last active April 24, 2016 19:01
Show Gist options
  • Save hectorhuertas/2e9ec67a7caaba8091311cea29d850d6 to your computer and use it in GitHub Desktop.
Save hectorhuertas/2e9ec67a7caaba8091311cea29d850d6 to your computer and use it in GitHub Desktop.
README Love

Super READMEs

Ideabox

Game Time

Personal Project

##PROTIP: README Love

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

####Things that make a README great:

  • A link to the production site on heroku
  • 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)
  • 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)
  • Directions on how to run the tests
  • Directions on how to seed the database (if relevant)

As projects grow, these instructions are vital to getting open source contributions...

But most importantly for students, READMEs are vital for helping classmates contribute, giving the repos a professional look and feel, and for impressing future employers.

You never know when a potential employer will be looking at your Github, so make your repos looks great.

####Examples of Good READMEs

  • Katrina Owen is the queen of documentation.
  • Apollo.io
    • I assure you, the website no longer works, but it LOOKS like it does on the repo
  • Jeff Casimir is pretty good at docs too
  • Jekyll
    • You don't have to cram all the documentation in one file, check out the Jekyll repo!

####Markdown References

Some Fancy README tricks!

Did you know you can embed screenshot gifs in a Readme?!
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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment