Writing by Peter Hilton

What to put in a README

How to minimally document software - 23 March 2021 #software #documentation

Writing at the top of blank page

unsplash-logoJ. Kelly Brito

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:

GitHub prompt to add a README

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.

  1. What it is
  2. Purpose
  3. Features
  4. Usage/examples
  5. Installation
  6. Asking questions
  7. Building from source
  8. Contributing
  9. Authors/maintainers
  10. 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