设计文档怎么写
设计文档(Design Doc)是架构师最重要的产出物之一。它的核心目的不是"展示我设计得多好",而是让读者在最短时间内理解:要解决什么问题、为什么这样设计、有什么权衡、怎么落地。
下面从类型、结构、写法、常见错误四个层面讲清楚,并结合你那个AutomaticStationPipeline给一个完整示例。
一、先分清文档类型
不同场景需要不同的文档,不要混在一起写:
| 类型 | 目的 | 篇幅 | 读者 |
|---|---|---|---|
| ADR(架构决策记录) | 记录一个具体决策及其理由 | 1–2 页 | 团队、未来接手者 |
| 设计文档(Design Doc) | 描述一个系统/模块的完整设计 | 5–20 页 | 开发、测试、运维、产品 |
| RFC(征求意见稿) | 提出方案,征求反馈 | 3–10 页 | 跨团队评审 |