| name | write-docs |
| description | Authoring docs in ppds-docs — Diátaxis classification, voice, style. Use when writing or restructuring tutorials, guides, reference, or concept docs. |
Write Docs
Conventions for the documentation site. Triggers when authoring or
reorganizing prose under docs/.
When to Use
- Writing a new doc page
- Refactoring an existing page that does not fit cleanly in one Diátaxis bucket
- Reviewing a PR that touches
docs/
Diátaxis Classification
Every doc fits exactly one of these buckets. If you cannot pick one, the
doc needs to be split.
| Type | Purpose | Voice |
|---|
| Tutorial | Learning-oriented, step-by-step | Hand-hold the reader through a complete experience |
| Guide | Task-oriented, goal-focused | Show the most direct path to the user's goal |
| Reference | Information-oriented, complete | Be exhaustive and predictable; no opinions |
| Concept | Understanding-oriented, explains why | Explain the model and tradeoffs; no procedure |
Mixing types in one page is the most common drift. A tutorial that becomes
a reference table is two pages.
Style Rules
- Second person ("you can...") for tutorials and guides.
- Third person for reference and concept docs.
- Present tense, active voice.
- Short paragraphs — 3–4 sentences max. Long paragraphs scan poorly.
- Code blocks must be correct and ready for use. Assume the reader
will copy them verbatim — no
todo, no fix in prod, no untested
placeholders. If a value must be substituted, surface it with an
explicit callout immediately above the block.
Doc Lifecycle
- Draft under
docs/<bucket>/<slug>.md with the right Diátaxis bucket.
- Add to sidebar in
sidebars.ts if surfacing to users.
- Run the docs site locally (
npm start) and proof at
localhost:3000.
- Submit PR — the docs CI runs link-checking and broken-image checks.
Why This Lives in a Skill, Not CLAUDE.md
Doc-authoring conventions only matter when writing prose. Loading them
into every Claude session in the docs repo would crowd out genuinely
global rules. The skill auto-loads when it is needed; otherwise it sits
idle.
