code-sample-documentation

Code Sample Documentation

Use this skill to create and review code samples that are useful, accurate, copyable, and maintainable. It applies to executable examples, explanatory snippets, API request/response pairs, CLI commands, config files, and generated references.

This skill is derived from Docs for Developers: An Engineer's Field Guide to Technical Writing, especially Chapter 5, "Integrating code samples." The guidance is transformed and paraphrased; do not copy book prose into user outputs. Source: https://link.springer.com/book/10.1007/978-1-4842-7217-6

Quick Start

1. Load guidelines.md to choose the smallest useful reference set.
2. Classify the sample as executable, explanatory, or paired request/response.
3. Check whether the sample is explained, concise, clear, usable, and trustworthy.
4. Use workflows/review-code-sample.md for a full sample review.
5. Prefer running or testing samples when feasible; otherwise mark what remains unverified.

Default Output

When reviewing or designing code samples, return:

1. Sample purpose - what the reader should learn or accomplish.
2. Sample type - executable, explanatory, request/response, CLI, config, or generated.
3. Issues or design notes - ordered by reader risk.
4. Revised sample - concise and copyable when requested.
5. Testing plan - how to verify runtime behavior, outputs, and version assumptions.
6. Maintenance notes - source of truth, owner, and generated/manual boundary.

Contents

| Need | Start Here |

|------|------------|

| Understand sample types | references/core/knowledge.md |

| Apply sample rules | references/core/knowledge.md |

| See before/after examples | references/core/knowledge.md |

| Review or design a sample | workflows/review-code-sample.md |

| Route by task | guidelines.md |

Core Posture

• A sample is documentation and software; treat it as both.
• Match sample complexity to the reader's stage.
• Make placeholders, inputs, outputs, and limitations explicit.
• Do not imply a sample is production-ready unless it has been reviewed and tested for that use.