Agent Skills: Documentation Standards

Documentation Standards

Critical rules

• Reader first: every decision answers "What does the reader need?" — not what the author knows.
• No lies: no broken links, untested examples, or outdated facts.
• Test everything: every code sample runs; every link resolves.
• Principles over templates: score quality dimensions; templates follow.
• Do not document obvious code, throwaway prototypes, or placeholders you cannot keep accurate — stale docs are worse than none.
• Before scoring quality or choosing a document type, read the matching resource below.

Workflow

1. Name the reader, their goal, prerequisites, and success criteria.
2. Pick the document type (README, API reference, tutorial, changelog, or error message). Before drafting sections, read references/document-types.md.
3. Draft for the reader's task: What → Why → How. Front-load purpose in the first two paragraphs.
4. Score against the eight quality dimensions. Before scoring, read references/quality-dimensions.md.
5. Make code samples copy-paste ready (imports, init, errors, output). Write error messages that state what failed and how to fix it. Before polishing prose or samples, read references/writing-and-examples.md.
6. Run the Validation checklist. Fix evidence-backed gaps only.

Resources

• references/quality-dimensions.md — clarity, accuracy, conciseness, structure, usability, consistency, completeness, examples. Read when scoring or reviewing.
• references/document-types.md — README, API reference, tutorial, changelog requirements and WRONG/CORRECT. Read when choosing structure.
• references/writing-and-examples.md — code-sample rules, sentence/paragraph principles, error messages, rationalizations, red flags. Read when drafting or polishing.

Validation

User-centered

• [ ] Target user, goal, prerequisites, success criteria, and next steps stated

Content

• [ ] First sentence explains purpose; active voice; terms defined; assumptions explicit

Code examples

• [ ] Imports, runnable, output shown, error handling, language tag, tested

Accuracy

• [ ] Signatures match code; version numbers current; links resolve

Constraints

• Not for long-form article arcs (spine-framework) or Agent Skill authoring (skill-authoring).
• Related: structured-writing (voice-preserving capture), system-architecture (ADRs), design-principles (domain naming in docs), data-visualization (diagrams over walls of text).