Documentation Generation

Write documentation that people actually read, understand, and trust — with automated workflows that keep it accurate.

Core Principles

1. Documentation Is Code — Treat It That Way

Store docs in the repository, version them with code, review them in PRs, lint them in CI. Documentation that lives in a separate wiki inevitably drifts from reality.

2. Write for the Reader's Context

Different readers need different documents. A junior developer onboarding needs a step-by-step tutorial. A senior engineer debugging needs API reference. A product manager needs architecture overviews.

3. Show, Don't Just Tell

Code examples are worth a thousand words of prose. Every API, every workflow, every pattern should be accompanied by a complete, runnable example.

4. Document Why, Not Just What

The code already tells you what it does. Documentation should explain the reasoning, the tradeoffs, and the edge cases that aren't obvious from reading the implementation.