Documentation Patterns

Package Doc Structure

1. Header: One paragraph — what it does, who uses it, why.
2. Quick Start: Minimal working example (3-10 lines), full imports, compiles.
3. Core Interface: Go interface definition.
4. Usage Examples: Basic, with middleware, with hooks, custom implementation.
5. Configuration: All

   WithX()

   options with defaults.
6. 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.