README Tips

This GitHub organization and repository has a single, simple mission: to help you create better, more useful README files for use in GitHub and elsewhere

Viewing this file

View this file as source code:

https://github.com/readmeTips/readmeTips.github.io

View this file as a web page using GitHub Pages:

https://readmeTips.github.io

Essential tips for a nice readme

• Assume you are reading your readme for the first time
• Assume you know nothing about
  • the project
  • the language it is written in
  • the dependencies
  • the intended audience
  • the features and benefits you provide
  • the history of the project
  • the people involved
  • the monetization
• Assume you have never seen your work at work
  • Provide a graphic
  • Link directly to an online working version
• Assume people want to use your work
  • Provide links to your license
• Assume you are also wildly popular
  • Have something for people what visit very regularly

Links to helpful pages about README files

Wikipedia README

• Includes the history of the README
• Explains the use of uppercase

Tom Preston-Werner Readme Driven Development

• One of the founders of GitHub

Readme file guides on GitHub: https://github.com/topics/readme

Stephen Whitmore Art of README

Patrick Balestra How to Improve Your GitHub README

• Some good technical tips

GitHub About READMEs

18F Making READMEs readable

Claire N Streb All Hail the README File!

GitHub: Open Source Guides

Richard Littauer Standard Readme

Create a home page auto-magically from README.md

If you are a GitHub user named %username% and and create a repository at %username%.github.io and add a README.md file, then the README file will be auto-magically be translated into HTML and will display as HTML when you go to https://%username%.github.io.

This README is a good example. Go to readmeTips.github.io to see the result.

Markdown cheat sheets

John Gruber Daring Fireball: Markdown Basics

• The creator of Markdown

GitHub Mastering Markdown