# Documentation Standards

> Frames documentation around reader needs using quality dimensions, document-type requirements, and review checklists. Use this skill when writing or reviewing READMEs, API references, tutorials, changelogs, or error messages. Do not use when/for long-form article structure (use spine-framework) or authoring Agent Skills (use skill-authoring).

- Skill: `jagreehal/documentation-standards` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add jagreehal/documentation-standards`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jagreehal/documentation-standards/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jagreehal (https://skillmd.com/u/jagreehal)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/jagreehal/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](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](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](references/writing-and-examples.md).
6. Run the Validation checklist. Fix evidence-backed gaps only.

## Resources

- [references/quality-dimensions.md](references/quality-dimensions.md) — clarity, accuracy, conciseness, structure, usability, consistency, completeness, examples. Read when scoring or reviewing.
- [references/document-types.md](references/document-types.md) — README, API reference, tutorial, changelog requirements and WRONG/CORRECT. Read when choosing structure.
- [references/writing-and-examples.md](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).