.agents/skills/docs-review/references/docs-principles.md
Good 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.
Storybook docs must work for two audiences simultaneously:
Write for the human first. Structure for both.
Use 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.
The 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.
The 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.
The 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.
Abstract ideas are grounded in concrete terms. Relationships between concepts are explicit. The reader can build a mental model, not just follow steps.
Procedures 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.
Code 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.
Every 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.