How to write a README

This file gives instructions and examples for writing README files for GitHub repositories.

Examples of well-written READMEs

• https://github.com/bcicen/slackcat
• https://github.com/gsamokovarov/jump
• https://github.com/rafaelrinaldi/whereami

General template

Name of project (big header, like H1)

One-sentence description of what it does—two sentences at most. If you have screenshots of your project running or of its output, put them here.

Installation / building (H2)

Show the actual commands someone must run to build the project, including fetching dependencies. Use fenced code blocks (triple backticks) so commands appear in monospace.

Usage (H2)

If it is a command-line app, list the available invocations (for example, git revert, git commit). If it is a web app, list the URLs.

Notes (H2)

This is where you talk about design ideas: algorithms, papers you have read, goals, and TODO items.