← Back to all articles
Reverse team

The Anatomy of a Good README

How to write project documentation that helps a new reader reach a working result quickly.

documentationopen sourcecraft

A README is often the first interface of a project. It should help a reader move from curiosity to a working local result without guessing.

The first screen matters

Put the essential facts near the top:

  1. What does this project do?
  2. Who is it for?
  3. How can someone run it?
  4. Where can they learn more?

Avoid making the reader scroll through badges before they see the first command.

A useful structure

# Project name
One sentence describing the project.

## Quick start
The shortest path to a successful run.

## Configuration
Environment variables and defaults.

## Development
Tests, linting, and local conventions.

## Deployment
Where the built artifact goes.

Explain the why

Commands explain what to type. A short sentence explains why the command is there. Compare:

Run npm run build to generate the static output in dist/.

with a list of commands that has no indication of expected results.

Documentation as a test

Try the quick start in a clean directory. Note every assumption:

  • Is the required runtime installed?
  • Does the lockfile describe the install?
  • Is a sample environment file included?
  • Does the first page actually load?

If a new contributor gets stuck, the README has discovered a bug in its instructions.

Good documentation is not a tour of every file. It is a reliable path to the first useful result.

The best README is allowed to be short. It should be complete before it is clever.