Documentation Patterns

Package Doc Structure

• Header: One paragraph — what it does, who uses it, why.

• Quick Start: Minimal working example (3-10 lines), full imports, compiles.

• Core Interface: Go interface definition.

• Usage Examples: Basic, with middleware, with hooks, custom implementation.

• Configuration: All WithX() options with defaults.

• Extension Guide: Implement interface → register via init() → map errors → write tests.

Rules

• Every concept needs a code example.

• Examples must compile with full import paths (github.com/lookatitude/beluga-ai/... ).

• Handle errors explicitly — never _ for error returns.

• No marketing language, filler words, or emojis.

• Professional, active voice, present tense, imperative for instructions.

• Cross-reference related packages and docs/ .

• Use mermaid diagrams sparingly (< 15 nodes).

• Tutorials: progressive complexity (basic 5min, intermediate 10min, advanced 15min).

Don'ts

• No phase references or timeline language.

• Don't duplicate architecture docs — link to them.

• Don't list every provider — point to docs/providers.md .

• Don't show incomplete examples that won't compile.