Prove Real Use With Examples
DOCS-PROVE-REAL-USE-WITH-EXAMPLES
Summary
Use examples that show realistic ownership, errors, lifecycle, configuration, or integration shape. Keep them focused, but make them strong enough to prove the contract.
Rule
Prove real use with examples.
Why
Examples that only construct a type or call the happy-path function do not prove that the API works in the way users need. A useful example shows ownership, errors, feature flags, lifecycle, input/output, or integration shape close enough to real use that readers can adapt it safely.
Helps
- Turns examples into contract evidence and prevents shallow examples from hiding missing integration details.
Limits
Keep examples focused. Do not build a full app when a smaller realistic slice proves the contract that matters.
Agent Instruction
Prove real use with examples because examples that only construct a type or call the happy-path
function do not prove that the API works in the way users need.Mechanisms
Supported by doctests, integration examples, example binaries, fixtures, snapshots, and review that asks what real user question the example answers. Use Separate Technique From Example Policy when a realistic example adds application decisions that readers could mistake for library requirements.