write-design-docs

编写设计文档

核心工作流

将设计文档用作解决问题和达成共识的工具，而不是实现手册。

1. 判断是否需要编写设计文档。

   • 当软件设计含糊、复杂、有争议、涉及多个职能、可能受益于资深人员评审，或值得作为组织记忆留存时，编写设计文档。
   • 当解决方案显而易见且没有实质性权衡时，优先选择简短说明、议题或直接实现。
   • 对于规模较小但不易理解的变更，优先选择迷你设计文档。

2. 收集足以让设计具体化的最少背景信息。

   • 确认问题、现有情况、约束、利益相关者和决策期限。
   • 只有在缺失的信息会实质性影响目标、非目标或权衡时，才提出有针对性的问题。
   • 在信息不完整的情况下继续推进时，明确说明假设。

3. 围绕决策和权衡起草文档。

   • 从客观背景和范围入手。
   • 将目标和非目标明确界定为边界。
   • 从概述到细节，说明选定的设计。
   • 解释为什么在已知约束下，选定的设计最能满足目标。
   • 比较现实可行的替代方案，包括未选择它们的原因。
   • 视情况涵盖安全、隐私、可靠性、可观测性、迁移和运维等横切关注点。

4. 保持文档易读。

   • 面向繁忙的评审者优化内容，让他们理解决策，而非了解每个实现细节。
   • 链接到详细需求、原型、架构、代码或先前的文档，而不是将其整份复制过来。
   • 仅在有助于阐明设计权衡时，才加入图表或简洁的 API／数据示意。
   • 除非需要解释新颖算法，否则避免使用大段代码块。

5. 规划文档生命周期。

   • 标注文档状态：草稿、评审中、已接受、实现中、已被取代或已归档。
   • 先建议由规模最小且有效的评审小组评审，待设计稳定后再扩大评审范围。
   • 如果实现过程中发现假设有误或需求已变，而系统尚未发布，则更新文档。
   • 如果原始文档与实际情况不符，则链接到修订说明或后续文档。

参考资料

起草或评审实质性的设计文档前，请阅读 references/design-doc-guidance.md。使用其中基于文章的模板、决策检查清单、章节指南和评审标准。