README

READMEs are ubiquitous in software development projects, but what should go in them? Too little information and your users and developers won’t know what to do with your project. Too much information and people will get lost trying to find what they need.

Your README is in some ways a combination of several of the other types of documentation discussed in this playbook. For example, the overview section in the README will be a summary of what would go in an ‘Overview’ page in the actual documentation.

There are two main questions you are trying to answer with your README, while keeping it as short as possible:

• Why would a user want to use my tool?
• How does a user use this tool? All extraneous information outside of this needs to go into the external documentation.

It’s good practice to have a new user go through your README and test everything before your repo is made public.

Writing Tip: If you need volunteers, offer to exchange your time for theirs. They might need someone to test their own code, review something they’ve written, etc.

Highlights of this section:

• What should go into a README vs. the external documentation
• Tips and suggestions for creating a README that is useful for people just discovering the project and long-time users

Remember that a Markdown template for the README is available in the companion template repository!