47 lines
2.8 KiB
Markdown
47 lines
2.8 KiB
Markdown
# Docs Guard — Code Sample Rules
|
|
|
|
A code sample is the most-trusted part of any documentation: readers paste it. That trust makes a broken sample worse than no sample.
|
|
|
|
## Contents
|
|
|
|
- Shippable sample checklist
|
|
- Realistic data
|
|
- Secrets and credentials
|
|
- Error-path examples
|
|
- Language and environment tags
|
|
- Sample drift
|
|
|
|
## Shippable sample checklist
|
|
|
|
Every sample must pass all of these:
|
|
|
|
1. **Imports resolve** — every import/require/use names a real module at the documented version.
|
|
2. **APIs are real** — every call verified per [verification.md](verification.md): name, argument order, defaults, return shape.
|
|
3. **Self-contained or explicit** — runs on a clean machine, or states its prerequisites immediately above the block ("requires the client from the previous step").
|
|
4. **No local residue** — no `/Users/yourname/`, no `C:\Dev\`, no machine-specific ports or hostnames; use placeholder conventions the project already uses.
|
|
5. **Syntactically valid** — parse it mentally line by line; when the runtime allows, actually run or lint it.
|
|
6. **Output shown is output produced** — if the sample shows a result, that result must be what the code yields, not an idealized version.
|
|
|
|
## Realistic data
|
|
|
|
Use data that exposes the API's shape honestly: realistic field names, plausible values, at least one non-ASCII string where text handling matters. `foo`/`bar` hides bugs that `"Café Münster"` reveals — especially for the i18n-aware audience.
|
|
|
|
## Secrets and credentials
|
|
|
|
- Placeholders that cannot be mistaken for real values: `YOUR_API_KEY`, `example.com`, RFC 5737 IPs (`192.0.2.x`), `sk_test_…` style markers only when the provider defines them.
|
|
- Never paste real-looking tokens — even invented ones train readers to paste theirs, and secret scanners will flag the repo.
|
|
- Auth setup goes in one place and is linked, not repeated with variations in every sample.
|
|
|
|
## Error-path examples
|
|
|
|
For any API that can fail in normal operation, show one failure: what the error object/exception/status looks like and the minimal correct response to it — using the error types the code actually raises (verify the raise site). Happy-path-only documentation produces catch-all error swallowing downstream, the exact failure clean-code-guard exists to stop.
|
|
|
|
## Language and environment tags
|
|
|
|
- Fenced blocks carry the correct language tag — broken highlighting is a trust signal readers notice.
|
|
- State the environment when it changes behavior: shell prompts (`$` vs `#`), OS-specific paths, version-gated syntax.
|
|
|
|
## Sample drift
|
|
|
|
Samples drift faster than prose because nobody re-runs them. On any code change touching a documented API, grep the docs for the old symbol (SKILL.md Rule 6) — samples are where the stale hits hide. Projects with executable-docs tooling (doctest and kin): prefer it; this skill's manual verification is the floor, not the ceiling.
|