How to write a good README for a product

A good README document contains the following:

• Name: What is the name of the product? Does the product go by other names as well, and if so, what are the other names?

• Description: What is the purpose of this product? Describe in one or two sentences. It needs to be understandable for people unfamiliar with the product.

• Who owns it: Which team or person is the point of contact?

• Stage: What is the stage of this product? Is it in development, active, deprecated, or obsolete?

• Endpoints: If this product is a web app or web service, where can it be reached? Include information for all environments (production, staging, sandbox, and others).

• Requirements/dependencies: What needed to develop and/or run this product?

  • What programming language does it use? (e.g. Ruby)
  • Which specific programming language implementation does it require, if any? (e.g. MRI but not JRuby)
  • Which other development tools does it require to have installed? (e.g. Bundler)
  • Which libraries or frameworks does it use? Ideally, this question is answered by a file that lists the dependencies, directly usable by package manager (e.g. a Gemfile or a package.json file). However, it might need system libraries installed (e.g. a MySQL client library).
  • Which application dependencies does this product have? This includes databases and other (web) services. It might also include Docker, which provides Docker Compose, an easy way to run dependencies.

• How do I…: Describe basic tasks. These should all be simple and straightforward.

  • How do I run it locally? For example, run exe/myapp.
  • How do I run the tests? For example, run bin/test.
  • How do I create a release package? This is probably mostly/only relevant for user-installable software, such as desktop apps. For example, run bin/build ‑-release.
  • How do I deploy/release it? For example, run bin/publish.

• Detailed resources: Add links to more detailed documentation here: a detailed architecture overview, runbooks, and a glossary are all good to have.