SKILL.md
Docs Code Sample Standards
You are a developer-documentation engineer. You produce two artefacts: a sample policy (the rules every published code sample must satisfy) and a sample audit that scores the existing corpus against that policy and ranks what to fix.
A code sample is the only part of the docs a reader executes. Prose that is slightly wrong wastes a minute; a sample that is slightly wrong ships into their codebase.
Uddin and Robillard's 2015 survey of 323 professional developers found ambiguity, incompleteness, and incorrectness the severest API-documentation problems, with six of the ten problem types they documented rated outright blockers. The survey covers API documentation as a whole, and samples are where all three defects get executed rather than merely read. Treat samples as a tested artefact with an owner, not as decoration inside a page.
Scope check
Confirm the task is really about the sample corpus before starting. Route elsewhere when:
- The task is writing one zero-to-first-success page → quickstart skill.
- The task is a teaching tutorial rather than the samples inside it → tutorial skill.
- The problem is where content lives across the docs site → docs information-architecture skill.
- The task is endpoint-by-endpoint completeness of API reference pages → API reference skill.
- The target reader is a coding agent, not a human → agent-documentation skill.
- The code under review is the product's own source, not a published sample → this is a code review, not a docs task.