Good readme

Write a good README

Apply the structure below when creating or improving a README. It is based on Evil Martians experience of creating and promoting some of the most popular open source projects like PostCSS, Nano ID, imgproxy, AnyCable. Companion to https://evilmartians.com/chronicles/how-to-make-your-open-source-popular.

Never invent facts. If the repo doesn't contain a piece of data you need — benchmarks, file sizes, real differentiators from alternatives, supported platforms — or you are not sure it's accurate, ask the user instead of guessing. A README with fabricated numbers is worse than one without numbers.

Structure: a "progressive JPEG"

The main risk is that the reader stops reading before finding a reason to care. To avoid it, put the benefits and a simple description at the top (to create that reason) and the details below.

0. Clean up

Badge rows hurt readability, so keep exactly three: version, CI, coverage, in that order. Delete every other badge. Put them in their own paragraph directly below the H1, one badge per source line (Markdown joins them into a single rendered row). If one of the three doesn't apply to the repo, omit it and keep the rest in order; a repo where none apply gets no badge row.

Exact URL templates per ecosystem are in references/badges.md. Read that file before writing or editing a badge row.

If a deleted badge carried a real fact (bundle size, dependency count, supported versions), state that fact as a bullet in the Facts list instead, where it reads stronger.

1. Opening block

The first paragraph is the most important part. It must answer three things:

• What it does — in plain, conversational language, as you'd explain it to a colleague at a bar. No jargon.
  • Bad: "Cybernetically enhanced web apps."
  • Good: "A web UI framework with a unique compiler that generates smaller JS files."
• How the user benefits — state it explicitly.
• What makes it different from alternatives.

If you don't know the real differentiators, ask the user.

2. Facts

Right after the first paragraph, put a bullet list of the project's most important facts, features, and numbers.

Optimize the list for scanning, not word-by-word reading (the reader still doesn't have enough motivation): lead each bullet with 1–2 bold keywords, then the evidence.

Concrete evidence beats promises:

• Real benchmark numbers ("16% faster than uuid") — ask the user for them or how to run them; never estimate.
• Exact sizes ("141 bytes minified + gzipped") — measure or ask.
• Side-by-side code comparison with the closest alternative.
• Screenshots/diagrams where they replace a paragraph of text.

3. Example

Then put a small example, because scanning code or a screenshot is faster than reading text.

For libraries, show a small self-explanatory usage example. It doesn't need every real setup step — it only illustrates (the real guide comes below). Keep it in 4–10 lines of code and show the output in a comment, so the reader sees the result without running anything.

Nano ID's opener demonstrates steps 1–3 on one screen:

# Nano ID

A tiny, secure, URL-friendly, unique string ID generator for JavaScript.

- **Small.** 118 bytes (minified and brotlied). No dependencies.
- **Fast.** 50% faster than UUID.
- **Safe.** It uses hardware random generator. Can be used in clusters.

```js
import { nanoid } from 'nanoid'
nanoid() //=> "V1StGXR8_Z5jdHi6B-myT"
```

Note: one sentence packs what + differentiators; each bullet leads with a bold keyword and backs it with a real number; the example is 2 lines with the output in a comment.

4. Getting started

After the intro, add a guide on how to use the tool.

Step-by-step, explicit commands for adding the tool to an existing project. The reader should be able to do it by just copying commands, without thinking. Every step must be there.

Validate by following the guide from scratch as if you'd never seen the project; fix every gap.

Formatting for skimmers

• Headings for hierarchy, bold for key points, horizontal rules between layers.

• Lists over dense paragraphs.

• Put must-not-miss lines in a GitHub alert. The five types are > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION], each on its own line with the content in the blockquote below it:

  > [!WARNING]
  > Version 3 drops Node 18. Pin to `^2` if you need it.
  

  GitHub renders these as colored callouts; every other renderer degrades them to a plain blockquote, so nothing breaks off-GitHub. Use two or three per README at most, because a page of callouts is a page with no emphasis. Bold is enough for anything less urgent.

• If the README is longer than ~2 screens, add a table of contents after the opening block.

• Every section should deliver a benefit early, because readers abandon at the first boring stretch.

Voice

Structure is half the job. Once the README is drafted, run the prose through the repo-prose skill, which owns sentence-level style for anything living in a repository, READMEs included. This guide decides what goes where; repo-prose decides how each sentence reads.

Do not use the humanizer skill here. It exists to restore a personal voice in essays and blog posts, and it explicitly excludes README and docs prose.

If repo-prose isn't installed, the minimum bar is: no hedging, no significance inflation, and no sentence that reads the same after you delete it.

Checklist before finishing

1. First paragraph alone sells the project (what / benefit / difference).
2. Every number and claim is real, sourced from the repo, the user, or an actual measurement.
3. The example is self-explanatory, 4–10 lines, and shows its output.
4. Getting started works from a clean machine.
5. Skimming only headings + bold text still tells the story.
6. The draft has been through repo-prose.