How to Write a README People Read

Your README has eight seconds. Spend them well.

The first line

What it does, not what it is. “Turns any text into a beautiful page in ten seconds” beats “A modular publishing framework leveraging…” every time, in every universe.

The order

1. What it does — one sentence
2. Show it working — one block, copy-pasteable
3. Install — the real commands, tested today
4. The one gotcha everyone hits — be honest, save them the issue ticket

The test

Hand it to someone tired. If they ask a question, the answer was missing. If they ask two, start over.

Documentation is hospitality. The reader is a guest who arrived hungry.

House rules for guests: default-settings-are-a-design.