How to write a good README for a product

Note last edited July 2021

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.

Note last edited July 2021.

Backlinks: Perpetual interests.

Thanks for reading.