Lead Docs with a Runnable Example
Readers learn a tool by running it, not by reading its options. A complete example that works on the first paste teaches more than three paragraphs of prose.
Procedure
- Open the section with the smallest complete example, including nothing omitted that would break it (imports, setup lines).
- Make the example self-contained: no "assume a configured client". Show the two lines that configure it.
- Show the expected output directly beneath, in its own fenced block, so the reader can compare.
- Order the example along the reader's task: build, run, observe. Not along the module's internal structure.
- Add a "what just happened" paragraph of two or three sentences after the output.
- Move to the options table only after the reader has a working mental model.
- Provide a second example that shows the one variation most readers need next (error handling, a different input).
- Keep the example under 20 lines; longer examples go to
examples/with a link and a filename. - Use real-ish values, not foo/bar;
users_tablebeatsx. - Give each example a name you can link to, so a bug report can cite the exact snippet.
- Note the version the example targets, so a reader on an older release knows it may not apply.
- Run the example verbatim from a clean checkout before publishing.
Pitfalls
- A "simplified" example that omits the line everyone forgets, so it fails when copied.
- Prose that describes each concept before the reader has seen it work, front-loading theory.
- Example output that no longer matches, so the reader thinks they broke it.
- A fragment hinting at an example without the surrounding variables, forcing guesswork.
- Examples that only show the success path, hiding the error a first-timer will hit.
- A sample whose printed output includes a timestamp, so every reader sees a "wrong" copy.
- Burying the runnable example below the architecture overview.
Verification
python -c "$(sed -n '/```python/,/```/p' docs/quickstart.md | sed '1d;$d')"
# extract and run the first example block; it must exit 0 and print the documented output
Confirm every fenced block in the doc runs as-is, and report any block that needed an edit to pass.