How to write a README that developers immediately understand

A README has one job: get a new developer from zero to running as fast as possible. Every word that doesn't serve that goal is waste.

Every project README needs, in this order:

1. What it is — one sentence. Not a marketing paragraph. One sentence.

2. Quick start — the exact commands to install and run it:

## Quick Start

git clone https://github.com/org/project.git
cd project
npm install
cp .env.example .env
npm run dev
# Server running at http://localhost:3000

3. Configuration — every environment variable explained. Don't just list them; explain what each does and what value to use for local development.

## Configuration

| Variable       | Required | Description                          |
|----------------|----------|--------------------------------------|
| DATABASE_URL   | Yes      | PostgreSQL connection string         |
| JWT_SECRET     | Yes      | Any long random string for local dev |
| SMTP_HOST      | No       | Email server, skip for local dev     |

4. API or usage examples — show the most important thing the project does with a concrete example. Not theory. Real code or real commands.

5. Contributing — how to set up the dev environment and what the PR process looks like.

What to skip: long architecture explanations (link to a separate doc), historical context, feature lists, and anything the code itself communicates. A good README is short. The best ones are under 200 lines.