docs-patternslisted

# Documentation Writing Patterns Before writing, **read 2-3 existing docs in the same category** to match their tone and structure. ## Writing Style **Tone:** Technical but accessible. Imperative for instructions ("Use X..."), declarative for specifications ("The User model has these fields..."). No marketing language. **Brevity is paramount.** A doc that could be 100 lines should not be 300. Every paragraph must earn its place. If a table communicates it better than prose, use a table. If a link to another doc covers it, don't restate it. Be precise, not exhaustive. ## Doc Types Pick the type before the shape -- the four Diataxis types each want a different shape. Two questions place any doc: **action** (doing) or **cognition** (understanding)? **Study** (learning) or **work** (the task at hand)? | Type | Purpose | Shape | Which am I writing? | |------|---------|-------|---------------------| | Tutorial | Learning-oriented -- teach a newcomer by doing | Guided, sequential lesson whose steps are guaranteed to work | "Teaching a beginner start-to-finish; if they follow along they succeed." | | How-to | Task-oriented -- reach one real goal with existing skills | Numbered steps for a single task; assumes competence | "Helping a competent user accomplish one specific goal." | | Reference | Information-oriented -- authoritative facts consulted mid-task | Austere, structured to mirror the code, consistent patterns and tables | "Describing what *is* -- consulted, not read thr