docs-authoring-ruleslisted

The compact rulebook to load BEFORE you write a new documentation page — not after. One pass over page type, structure, retrieval, style, audience, next-step and links, so the page ships without the defects the audit skills keep finding. Use whenever you are about to author or draft a new page, section or generated docs set. This is a guardrail, not an audit — it never analyzes or repairs existing pages.
Docsbook-io/docs-skills · ★ 1 · AI & Automation · score 75

Install: claude install-skill Docsbook-io/docs-skills

# docs-authoring-rules — Get It Right While Writing **Mode: authoring guardrail.** Three modes exist and they must not blur: | Mode | Trigger | Output | Forbidden | |---|---|---|---| | audit | docs exist, something is wrong | a report | changing anything | | refactor | docs exist and are bad | edits that preserve meaning | inventing new pages | | **authoring guardrail (this)** | you are about to write | a page that is already correct | **fixing old pages** | Notice a defect on a *neighbouring* page while writing? Note it and move on. Repairing it belongs to `docs-style-tone` / `docs-structure-templates` / `docs-navigation-linking` in audit or refactor mode. Mixing modes is how "write one page" becomes a rewrite nobody asked for. **Load this before the first line of a new page** — drafting a page or section from scratch, generating a docs set, expanding an outline into prose. Not for reviewing something already written; the audits do that better, and this rulebook has no findings format on purpose. --- ## 1. Decide the page type first Pick exactly one Diátaxis type before writing a word. The type decides structure, tone and what is off-limits. - **Tutorial** (learning) — one guaranteed path, imperative steps, a stated start and end state. No alternatives: "you can also use the CLI" belongs in a how-to. - **How-to** (task) — one real goal, competent reader, may branch ("if X, do Y"). No teaching foundations mid-task; link out instead. - **Reference** (information) —