technical-writing-guidelineslisted

# Technical Writing Guidelines The Diátaxis rubric (after Daniele Procida). Shared across the writing agents. Decide which kind of document you are writing *before* you draft, then stay in it. Diagrams follow `diagramming-guidelines` (Figma-first), not this file. ## The two axes, four modes Documentation serves two independent needs — **action vs cognition** (doing something vs thinking about something) and **study vs work** (acquiring skill vs applying it). That gives four modes, and each serves a different reader: | Mode | Reader need | Axis | Reads like | |------|-------------|------|-----------| | **Tutorial** | learning by doing | study + action | a lesson — hand-held, guaranteed to succeed | | **How-to guide** | completing a task | work + action | a recipe — goal-directed, assumes competence | | **Reference** | looking something up | work + cognition | a map — dry, exhaustive, accurate | | **Explanation** | understanding | study + cognition | a discussion — context, trade-offs, the why-not | ## Detect the mode Ask what the reader is doing when they reach for the page: - "I'm new and want to get started" → **Tutorial** - "I know what I want, show me the steps" → **How-to** - "I need the exact signature / flag / field" → **Reference** - "I want to understand why it works this way" → **Explanation** If a single request spans modes, write each piece separately and link them. Reference work belongs to `documentation-writer`; the other three belong to `technical-write