用例

技术文档

API 文档、架构记录、用户指南和运行手册,并配有结构化评审。

概述

API 文档、架构决策记录、用户指南和运行手册都能从结构化的创建与评审流程中受益。Datarim 确保文档准确、完整,并针对真实系统进行测试。该流水线可避免文档写一次就再也不验证的常见失败模式——每个端点都会被检查,每个示例都会被测试,每个链接都会被校验。

示例:支付服务的 API 文档

团队需要为一个包含 12 个端点的支付处理服务编写完整的 API 文档。文档必须面向第三方集成方,并包含三种编程语言的可运行代码示例。

流水线走查

阶段发生什么
/dr-init范围:12 个端点、请求/响应模式、错误码、认证流程(L2)
/dr-prd受众:第三方集成方。要求:OpenAPI 3.1、3 种语言的代码示例、沙箱 URL
/dr-plan优先级:先认证流程,再支付生命周期(创建 → 捕获 → 退款),最后 Webhook
/dr-do编写文档。与实际 API 代码交叉引用以确保准确性
/dr-qa验证:每个端点都有文档、示例已测试、错误码完整、链接有效
/dr-archive(步骤 0.5)备注:从实际 API 响应生成示例比手动编写更快

主要收益

  • 通过交叉引用保证准确性——文档会对照实际 API 代码进行验证,而非基于对行为的假设
  • 受众优先的设计——PRD 阶段明确文档的读者及其需求,避免以开发者为中心的盲区
  • 经过测试的示例——QA 确保每个代码示例在每种列出的语言中都确实可用
  • 活文档——API 变更时可重新运行流水线,由 QA 发现过时的章节

相关智能体

此用例中最活跃的智能体:

  • 写作者——以清晰的结构和示例起草文档
  • 编辑——一致性、术语和格式评审
  • 开发者——验证代码示例并与源代码交叉引用
  • 评审者——完整性检查和链接校验

复杂度路由

复杂度级别如何应用于技术文档:

  • L1——更新单个端点的描述或修复损坏的代码示例
  • L2——为包含 10-15 个端点的新 API 编写文档,包括模式和示例
  • L3——创建完整的开发者门户,包含指南、教程和参考文档
  • L4——多产品文档套件,包含版本管理、迁移指南和 SDK 参考