如何编写一份有效的软件设计文档
本文系统地介绍了如何撰写高质量的软件设计文档。文章涵盖了设计文档的核心目的、目标受众、文档结构（包括背景介绍、目标、非目标、系统架构、数据模型、API设计等关键部分），以及编写过程中常见的陷阱和最佳实践。通过遵循本文提供的框架，工程师可以创建清晰、完整且易于评审的设计文档，从而提升团队协作效率和项目成功率。
背景速读
- 软件设计文档（Design Doc）是工程师在动手写代码前撰写的技术方案，用来明确要解决的问题、系统架构、权衡取舍和实现计划。在 Google、Meta 等大型科技公司，写设计文档是标准流程，目的是让团队在投入大量工程资源之前对齐思路、提前发现设计缺陷。
- 文章所针对的痛点：很多工程师要么不写文档，要么写得太长太技术、缺乏结构，导致文档无人阅读或无法指导实际开发。作者主张设计文档应当"先窄后宽"——先聚焦于要解决的具体问题，再逐步展开设计决策。
- 文中反复强调的"反对意见（Counterarguments）"和"权衡（Trade-offs）"并非可有可无的补充，而是设计文档的核心价值：记录为什么选择了方案 A 而不是 B，帮助未来的读者（包括几个月后的自己）理解当时的思考。
- 作者的核心理念公开在 Refactoring English 网站上：好的技术写作不是"把中文翻译成英文"，而是用清晰的结构和逻辑让复杂技术内容对读者友好。这篇文章延续了这一理念，专注于技术文档的"可读性"和"决策的可追溯性"。