The README shows how to install the project and one runnable example, in that order, near the top
Installation and a working snippet answer the two questions every visitor has. Burying them under motivation, philosophy, or comparison tables costs you the readers who would have used the project. A snippet that never shows what it returns makes the reader install the project to find out, which is the work the snippet was there to save.
Observable check
README.md contains a fenced code block with an install command, followed by a second fenced code block showing minimal usage whose result is visible in a comment inside the block or in a block immediately below it, and both appear before any section about design, motivation, or comparisons.
Where this comes from
- https://github.com/evilmartians/agent-skills/blob/main/skills/good-readme/SKILL.md
- https://evilmartians.com/chronicles/how-to-make-your-open-source-popular
Last read against these sources on 2026-07-28.
Same provenance and same caveat as R-DOC-01. Upstream gives the example its own specification, self-explanatory, 4 to 10 lines, output shown in a comment, and requires a getting-started guide explicit enough to copy without thinking. This rule diverges on order, and the divergence is deliberate: upstream runs opening, facts, example, getting started, putting the example before installation, where this rule requires install then example. oss-readme merges the two into one Install and example section to match.