GEO GUIDE
Writing a README: Strangers Running It in Five Minutes
Updated 2026-10-19 · this page makes no search or citation promises
The direct answer: a good README gets a stranger through understand-install-run in five minutes. Seven sections: one-line description, install, quick start, usage, configuration, known limits, contributing. Every command copyable, every example runnable — a broken example is worse than none.
The direct answer: a good README gets a stranger through understand-install-run in five minutes. Seven sections: one-line description, install, quick start, usage, configuration, known limits, contributing. Every command copyable, every example runnable — a broken example is worse than none.
The seven sections
- 1. One-line description: the problem the project solves.
- 2. Install: full commands with prerequisites.
- 3. Quick start: the fewest steps to one successful run.
- 4. Usage: the two most common scenarios.
- 5. Configuration: one line per option.
- 6. Known limits: stated honestly.
- 7. Contributing and licence: links to the details.
How to write commands
- Commands in their own code blocks, copyable as a whole.
- Real values in the commands (no <placeholders> mixed into copyable text).
- State the working directory and prerequisites.
Three common failures
- API reference without a quick start — readers who cannot run it leave.
- Examples depending on unstated hidden steps.
- README out of sync with the code after a version bump.
Self-check
Hand the README to someone on a clean machine and watch them follow it — five minutes to a working run is the only standard.