Scaffold Docs

Build technical documentation for a code library iteratively, top-down, with user review at each step. Doc writing is a subset of writing. Prose quality is in scope, not only structure.

Core principles

These shape every decision. Hold to them.

1. Write for a specific audience. You write documentation for someone. The primary audience (selected in Phase 1b) governs every later choice: use case, scaffolding, benefit framing, what to explain, what to skip. Apply references/audience-check.md throughout. Secondary audiences are tie-breakers; they never outrank the primary.
2. Mental model first. Documentation gives the reader a working mental model of the library, not a transcript of the code. When deciding what to include or cut, ask: does this advance the reader's mental model?
3. User's mental model, not package layout. Group content by what the reader is trying to do. Source-code directory structure is rarely the right structure for the docs.
4. Why over what. When a design decision matters for understanding or correct usage, explain why it was made, not only what it is. Use code comments, naming choices, and code smells as evidence of intent.
5. Surface only the dependencies a reader needs. For any topic, identify what it depends on, then communicate only the dependencies necessary to form a working mental model for that topic.
6. Progressive disclosure. The reader should never have to understand the whole library to start using it. Layer the docs so they can stop at any depth and still have a usable mental model.
7. Iterate, never one-shot. Each phase ends in a user review. Do not proceed to the next pass until the user has approved the current one.
8. Clear but not dry. Prose quality is part of the deliverable. Apply references/prose-style.md during every prose pass.

Output structure