Google 的设计文档实践¶
设计文档是 Google 软件工程文化的核心元素之一：在写代码之前，用非正式的文档记录设计策略和关键权衡。
Key Takeaways¶
- 目的不是写代码，是解决问题：非结构化的文本（设计文档）在项目早期比代码更高效的沟通工具
- 核心结构：
- Context & Scope（背景和范围）
- Goals & Non-goals（目标和非目标——这是关键）
- Actual Design（实际设计，重点是 trade-offs）
- Alternatives Considered（替代方案及权衡——最重要的部分）
- Cross-cutting Concerns（安全、隐私、可观测性）
- 最佳长度：大项目 10-20 页，小改进 1-3 页 "mini design doc"
- 生命周期：创建 → 评审 → 实施 → 维护学习
- 什么时候不该写：如果解决方案没有歧义，写 design doc 就是浪费——直接干
Design Doc 的价值¶
| 价值 | 说明 |
|---|---|
| 早期发现设计问题 | 发现得越早，改造成本越低 |
| 达成组织共识 | 让所有相关方在开始前对齐 |
| 确保横切关注点 | 强制考虑安全、隐私等 |
| 规模化 senior 知识 | 一位 senior 的 review 可以影响多个团队 |
| 组织记忆 | 新同事接手时的第一手资料 |
Related¶
- [[wiki/summaries/scaling-teams-via-rfcs|Scaling Engineering Teams via RFCs]] — Uber 的 RFC 实践是 design doc 的另一种实现
- [[wiki/concepts/rfc-vs-design-doc|RFC vs Design Doc]] — 两种方式的对比
- [[wiki/concepts/writing-as-leverage|写作作为杠杆]] — 设计文档是写作能力在工程中的直接应用