Documentation

Coverage

• Document type selection: deciding between reference doc, tutorial, guide, how-to, and architecture note based on the reader's need
• Audience fit: matching depth, vocabulary, and assumed context to the intended reader
• Progressive disclosure: ordering information so the most important facts appear first and detail unfolds on demand
• Docs-as-code workflow: keeping documentation in the repo, versioned alongside the code it describes, and reviewed in the same pull requests
• Freshness and drift: recognizing when documented behavior has diverged from real behavior and treating drift as a bug
• Source-of-truth discipline: citing verifiable sources and avoiding restatement of content that lives authoritatively elsewhere

Philosophy

Documentation is a product, not a deliverable. It is consumed under time pressure by someone who did not write it, and it ages against a codebase that moves without asking permission. The test of good documentation is a single question: does the reader reach the correct mental model faster by reading the doc than by reading the code? Everything else — format, length, voice, tone — follows from that one test. Docs that fail it waste everyone's time twice: the writer's on the way in, and every reader's on the way out.

Doc-Type Selection

Pick the doc type by the reader's need, not by the author's content. A reader looking for "how do I do X" will not read a reference; a reader looking up a field will not read a tutorial. The wrong type is worse than a missing doc because it consumes attention before failing.