What to put in a README
How to minimally document software 2021-03-23 #documentation
GitHub has probably done more for modern software documentation than anyone since Aaron Swartz and John Gruber invented Markdown in 2004 (except of course for HTML itself), by promoting README files:
Despite Markdown README files’ popularity, software developers typically either don’t know what to include, or leave out important information. A standard outline solves this.
Standard README outline
I recommend the following README outline (template below), which includes enough to have better documentation than nearly every GitHub repository. Ten sections seems like a reasonable compromise between documentation length and breadth, as several only require one or two sentences.
- What it is
- Purpose
- Features
- Usage/examples
- Installation
- Asking questions
- Building from source
- Contributing
- Authors/maintainers
- License
Some sections only apply to open source software, or software libraries that you share with third-parties. For different contexts, such as enterprise line of business software or commercial product development, adjust the standard outline to cover relevant topics.
Answer three basic questions
Before you can adjust the standard outline to your own context, you need to understand which questions an effective README answers. Grouping the standard sections illustrates this:
| 1. Should I use this? | 2. How can I use it successfully? | 3. How can I participate? |
|---|---|---|
| What it is Purpose Features License |
Usage/examples Installation Asking questions |
Building from source Contributing Authors/maintainers |
These questions help you understand the reader’s perspective when they first discover your software and its README. In particular, they first address relevance, in the same way as Vanguard’s three questions to ask about any tool.
Depending on your context, and what kind of software you need to document, you might need different information to answer these questions. You can also choose your top ten headings from the following options.
| 1a. Should I really use this? | 5. How do I get it to work? | 6. How it works |
|---|---|---|
| Status (does it work?) Known issues/bugs FAQ Security Background Alternatives Target users (who it’s for) Scope & limitations Constraints Hardware requirements Prerequisites |
Troubleshooting Version Change log Reporting bugs Testing Code of conduct Copyright information Contributors To do list Further information |
Deployment Platforms Architecture Components Physical structure Inputs & outputs Algorithm choices Lessons learned Jargon used |
Note that history doesn’t appear on any of these lists. Your readers don’t care. If you must indulge yourself, document that separately.
Incremental software documentation
Starting with a small README helps you document your software incrementally, starting with one sentence on each topic. For each section that needs more than a few short paragraphs, add a new document that focuses on one of the outline topics. For example, all but the most stable development terms benefit from more detailed development environment documentation.
A README that provides minimum viable documentation can also become the basis of more detailed documentation, when necessary. You don’t need more than a README for some software, but most software has at least one complex area that justifies more detailed documentation. Compared to more complex documentation approaches, starting with a README scales down enough to actually get used.
Markdown template
## What it is
## Purpose
## Features
## Usage/examples
## Installation
## Asking questions
## Building from source
## Contributing
## Authors/maintainers
## License
