writing-docslisted

Use when writing, restructuring, or reviewing any prose documentation — a tutorial, how-to guide, reference page, or explanation/conceptual doc — for a public docs site (e.g. Mintlify MDX, docs/, README material), a getting-started guide, an API/CLI reference page, or a "why we built it this way" conceptual page. Applies the Diátaxis framework (see https://diataxis.fr/) — every document belongs to exactly one of the four quadrants (tutorial / how-to guide / reference / explanation), and mixing quadrants inside one document is the single most common documentation failure. Covers the four-quadrant compass for picking the right form, per-quadrant structure templates, an anti-pattern list for quadrant drift, and generic voice/craft rules — repo-specific voice and target output format (e.g. Mintlify MDX) are resolved from the repo's docs-manifest (falling back to project-context), never hardcoded here.
whimzyLive/nightshift-ai · ★ 3 · AI & Automation · score 71

Install: claude install-skill whimzyLive/nightshift-ai

# writing-docs — Diátaxis documentation authoring **Core principle:** a documentation page serves exactly ONE of four distinct reader needs — learning, doing, looking something up, or understanding — and trying to serve two at once makes it worse at both. If you find a document explaining theory in the middle of a set of steps, or a reference page arguing for why a default was chosen, that's not richness, that's quadrant drift, and the fix is to split it, not to smooth it over. **Announce at start:** "I'm using the writing-docs skill to author/review this doc." ## Canonical source This skill distills [Diátaxis](https://diataxis.fr/) (Daniele Procida) — read the live site for the full treatment; the four-quadrant model, the compass, and the per-quadrant principles below are drawn from it directly, not invented here. When in doubt about an edge case this skill doesn't cover, the canonical source is the tiebreaker. ## When to Use - Whenever you're about to write or substantially restructure a prose documentation page — a tutorial, a how-to guide, a reference page, or an explanation/conceptual page — for a public docs site or any repo documentation meant to be read (not a code comment, not an ADR — ADRs have their own `writing-adrs` skill and their own format for a different purpose: a permanent decision log, not reader-facing product/project documentation). - When the sdlc docs pipeline (`/sdlc:docs` command + `knowledge-engineer` agent) generates or updates a do