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
- Asking questions
- Building from source
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
|Building from source
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?)
Target users (who it’s for)
Scope & limitations
Code of conduct
To do list
Inputs & outputs
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.
## What it is ## Purpose ## Features ## Usage/examples ## Installation ## Asking questions ## Building from source ## Contributing ## Authors/maintainers ## License