Writing a README people use

The README is the first thing anyone sees — a teammate, a contributor, an agent, future-you. A good one gets a stranger from "what is this?" to "it's running" in minutes. You learned to read docs; now you write the most important one.

The questions a README must answer

In roughly this order, top to bottom:

1. What is this? One or two sentences. What it does and who it's for.
2. How do I run it? Prerequisites, install, and the command to start it — copy-pasteable.
3. How do I use it? A minimal example of the main thing it does.
4. How do I develop/test it? For contributors: build, test, conventions.
5. Where do I learn more? Links to deeper docs, license, contact.

A newcomer reads top-down and should be able to stop as soon as they have what they need. Put the highest-value, most-common information first.

Write for someone who knows nothing

The curse of knowledge is the enemy of a good README. You know the project; your reader doesn't. Concretely:

• Spell out every setup step — the one you do automatically is the one they'll miss.
• Make commands copy-pasteable and tested; a command that doesn't run is worse than none.
• Prefer a working example over prose. People copy the example.

Keep it honest and current

A README that describes how things used to work erodes trust fast. Update it in the same commit as the change it describes, and delete anything you're not keeping accurate. A short, true README beats a long, stale one.

Where to go next

The README documents the project from outside. Next: docstrings and comments — documenting the code from the inside, and knowing when not to.