How to Write a Good README Developers Actually Use

Your README is the landing page most developers see first. Not your marketing site. The repo page.

A developer lands there with one question: "Is this worth ten minutes of my time?" A good README answers that in the first screen, then gets them to a working result before they lose interest. Everything else is secondary.

This guide covers what to put in a README, what order to put it in, what to cut, and a checklist to run before you make the repo public.

What a README is for

A README has three jobs, in this order:

1. Qualify. Tell the reader what this is and who it is for, fast enough that the wrong reader leaves and the right one keeps going.
2. Get them to first success. Install, run, see output. The smallest useful example.
3. Route them. Point to full docs, support, contributing and license.

It is not your full documentation. Google's documentation style guide describes a README as a short summary of a directory's contents, with links out to fuller docs. That is the right mental model. When a section starts growing past a screen, move it to a docs site or wiki and link to it.

The order that works

Developers scan top to bottom and stop early. Put the things that decide "keep reading or leave" at the top.

Badges, screenshots and GIFs are optional. Use them when they show something words cannot, like a CLI's output or a UI. Skip them when they are decoration.

Step 1: Write the one-line description

This is the most important line in the file. Name the thing it does, not the category it wants to be in.

Bad:

A next-generation, developer-first platform for modern data workflows.

Good:

Sync Postgres tables to S3 as Parquet files on a schedule.

The good version tells a reader in five seconds whether they have this problem. The bad one tells them nothing.

Test: could someone repeat your one-liner to a teammate and have the teammate know what it does? If not, rewrite it.

Step 2: Write the short pitch

Two to four sentences under the one-liner. Cover:

• Who it is for. "For teams running Postgres who need analytics copies without a full ETL stack."
• What it removes. "No cron scripts, no hand-rolled exports."
• How it differs. One honest line on why this and not the obvious alternative.

Make a README recommends noting what sets your project apart from alternatives and linking any terms a reader might not know. Do both. Do not oversell. Developers read "fastest" and "easiest" as unverified claims.

Step 3: Make the quickstart the center of the file

This is where you win or lose the reader. The goal is time to first success: the shortest path from "I found this" to "I saw it work."

Rules for a quickstart that works:

• One install command. If there are prerequisites, list them right above it.
• One copy-paste example. It should run as written, with no edits except an API key or path, and those should be clearly marked.
• Show the expected output. Readers need to know what "it worked" looks like.
• No branching. Pick the most common setup. Link to the others.

pip install pgsync-parquet
export DATABASE_URL="postgres://user:pass@localhost:5432/app"
pgsync-parquet run --table orders --bucket s3://my-bucket/exports

Exported 12,480 rows from orders -> s3://my-bucket/exports/orders/2026-10-30.parquet

Then run it yourself from a fresh clone on a clean machine, following only the README. Most broken quickstarts were never followed from zero by their author.

Step 4: Add usage for the next two or three tasks

After first success, readers want to know whether the tool handles their real case. Pick the two or three tasks most people do next and give each a short heading and example.

Good usage headings

• "Export only rows changed since the last run"
• "Run on a schedule"
• "Write to a local directory instead of S3"

Task-shaped headings beat feature-shaped ones because readers search by what they are trying to do.

Step 5: Requirements and configuration

Be explicit. Make a README advises assuming the reader may be new and listing required language versions, operating systems and manual dependencies. Experts benefit too: an undocumented version mismatch costs anyone twenty minutes.

Use a table for configuration:

Step 6: Route them

Close with the links a reader needs next:

• Docs: full reference and guides.
• Support: issue tracker, discussion board or chat. Say which one you actually watch.
• Status: stable, beta or no longer maintained. If you have stopped working on it, say so near the top. Both guides referenced here call out status as something readers need.
• Contributing: setup, lint, test commands, or a link to CONTRIBUTING.md.
• License: one line, plus the LICENSE file.

Common mistakes

• Leading with the backstory. Why you built it can go at the bottom, or nowhere.
• An install section that assumes your machine. Global tools, env vars and services you forgot you had.
• Examples that drifted from the code. Run your README examples in CI if you can.
• Writing it last. Make a README suggests writing the README first. It forces you to define the user and the happy path before you build too much.

README template

# project-name

One line: what it does, in plain words.

Two to four sentences: who it is for, what it removes, how it differs.

## Quickstart

Prerequisites: <runtime + version>, <service>.

    <install command>
    <minimal working example>

Expected output:

    <what success looks like>

## Usage

### <Common task 1>
### <Common task 2>

## Configuration

| Variable | Required | Default | What it does |

## Docs and support

- Docs: <link>
- Questions: <where you actually answer>

## Status

<Stable | Beta | Unmaintained>

## Contributing

<Setup, test, submit, or link to CONTRIBUTING.md>

## License

<License name>

Pre-ship checklist

• The one-liner says what it does, with no category buzzwords.
• A new reader knows who it is for within the first screen.
• The quickstart has one install command and one runnable example.
• Expected output is shown.
• I followed the quickstart from a fresh clone on a clean machine.
• Required versions, OS and external services are listed.
• Config options are in a table with defaults.
• Usage covers the next two or three real tasks, with task-shaped headings.
• Docs, support channel, status and license are linked.
• Anything longer than a screen has moved to the docs site.

Do this next

Open your README, cover everything below the first screen, and ask: would a stranger know what this is and how to try it? If not, fix the one-liner and the quickstart before anything else. Those two carry most of the weight.

If you want the rest of the launch handled the same way, from positioning and messaging to docs, launch assets and a day-by-day plan, The Developer Launch Kit includes a docs and quickstart chapter, fill-in templates and agent skills that draft from your repo. Get it here: https://shiptodevs.com/#pricing

Sources

• Make a README: https://makeareadme.com/
• Google documentation style guide, READMEs: https://google.github.io/styleguide/docguide/READMEs