docs-review

Source excerpt starting at line 1.

1# Docs Principles2 3## North Star4 5Good documentation reduces **time-to-understanding** or **time-to-success** for the reader. Every edit, restructure, or rewrite should move the page closer to one of these outcomes.6 7## Dual-Reader Requirement8 9Storybook docs must work for two audiences simultaneously:10 111. **Frontend developers** scanning for answers, examples, and steps they can act on immediately.122. **LLMs and retrieval systems** that parse docs for accurate, structured information to surface in AI-assisted workflows.13 14Write for the human first. Structure for both.15 16## Quality Dimensions17 18Use these dimensions to evaluate whether a page is doing its job. They are ordered from most structural to most surface-level — fix the top of the list before polishing the bottom.19 20### 1. Intent Clarity21 22The page states what it will help the reader do or understand within the first two sentences. A reader (or retrieval system) can decide whether this page is relevant without scrolling.23 24### 2. Audience Fit25 26The page assumes the right level of prior knowledge. It does not over-explain web fundamentals or under-explain Storybook-specific behavior. It meets the reader where they are.27 28### 3. Information Shape29 30The page is organized around the reader's task or question, not around the feature's implementation. Sections follow a logical progression: context → action → result, or definition → usage → edge cases. When a page contains secondary sections of a different doc type, each section follows the progression appropriate to its own type.31 32### 4. Conceptual Clarity33 34Abstract ideas are grounded in concrete terms. Relationships between concepts are explicit. The reader can build a mental model, not just follow steps.35 36### 5. Task Usability37 38Procedures are complete, ordered, and testable. The reader can follow them without guessing at missing steps. The default path comes first; variations and edge cases follow.39 40### 6. Example Quality41 42Code examples are representative of real usage, not minimal to the point of being misleading. They demonstrate the concept or task the page is about, not just syntactic validity.43 44### 7. Economy45 46Every sentence earns its place. Redundant explanations, filler transitions, and throat-clearing preamble are removed. Brevity serves the reader — but not at the cost of clarity.47