Back to Details

doc-writing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
  1. 标题部分：一段文字——说明该包的功能、适用人群及使用价值。
  2. 快速入门：最简可运行示例（3-10行代码），包含完整导入语句，可直接编译运行。
  3. 核心接口：Go接口定义。
  4. 使用示例：基础用法、结合中间件、结合钩子、自定义实现。
  5. 配置说明：所有
    WithX()
    选项及其默认值。
  6. 扩展指南：实现接口 → 通过init()注册 → 映射错误 → 编写测试。

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).
  • 每个概念都需附带代码示例。
  • 示例必须包含完整导入路径（
    github.com/lookatitude/beluga-ai/...
    ）且可编译运行。
  • 显式处理错误——错误返回值绝不能用
    _
    忽略。
  • 禁用营销话术、冗余词汇及表情符号。
  • 采用专业、主动语态、一般现在时，指令使用祈使语气。
  • 交叉引用相关包及
    docs/
    目录下的内容。
  • 谨慎使用mermaid图表（节点数<15）。
  • 教程：按复杂度递进（基础版5分钟、中级版10分钟、高级版15分钟）。

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.
  • 不得提及阶段或时间线相关内容。
  • 不要重复架构文档内容——直接链接至对应文档即可。
  • 无需列出所有供应商——引导至
    docs/providers.md
    。
  • 不得展示无法编译的不完整示例。