如何编写技术设计文档

TLDR

技术设计文档（又称技术设计文档或技术规格）是创建功能或技术问题解决方案详细方案的绝佳方式，无需编写任何代码。它们最终可以为您的团队节省大量时间。

大纲

• 技术设计文档的重要性
• 何时创建技术设计文档
• Mage 的技术设计文档模板
• 目的
• 背景/上下文
• 要求
• 详细设计
• 实施计划
• 测试
• 运行手册

技术设计文档的重要性

技术设计文档是解决技术问题或构建功能的说明。如果您准备好了，可以将其交给其他团队成员，即使他们经验不足或不熟悉当前问题，他们也应该能够解决问题。设计文档可以作为其他团队成员参考的文档形式。

此外，创建技术设计文档的过程会迫使你思考各种可能遇到的极端情况和问题，并提出解决方案。这个过程让你在脑海中构思解决方案，因此，当真正需要编写代码时，执行速度会快得多，因为繁重的脑力劳动已经完成了。

设计文档应该在共享工作区（例如 Google Docs 或 Notion）上完成，以便其他人可以发表评论并提供反馈。因此，设计文档不仅有利于委派工作、节省时间，还能促进协作以找到技术解决方案。

何时创建技术设计文档

一般来说，当你尝试解决一个需要超过一天时间才能解决的技术问题时，创建一份技术设计文档是个好主意。即使解决方案只需要几个小时就能实现，设计文档仍然很有用。

然而，大型项目和小型功能的设计文档篇幅显然会有很大差异。小型功能的设计文档本质上可以是伪代码，只要能够达到文档的目的，那就没问题。关键在于设计文档要有目的、要解决的问题和解决方案。设计文档中有一些通用部分可以用作模板，我们将在下文详细介绍，但并非所有设计文档都必须包含所有这些部分。

对于非常小的功能或技术问题，如果解决方案非常明显且实施时间很短，通常不需要设计文档。这有点主观，但如果设计文档实际上不会为您节省太多时间，并且编写它的好处不明显，那么您可能不需要编写它。

Mage 的技术设计文档模板

下面的每个部分都属于 Mage 团队成员在创建新设计文档时开始使用的设计文档模板的一部分。

在文档顶部，您应该包含作者姓名以及文档创建或最后修改日期。在 Mage，设计文档通常针对 Airtable 中的一个或多个史诗故事编写，因此添加指向 Airtable 史诗故事的链接会很有帮助。

目的

目的描述服务或功能的作用。尽量用一句话来概括。

背景

为什么需要这个功能？你想解决什么问题？其他团队成员阅读这份文档的背景是什么？

要求

这项服务或功能必须展现哪些成果？这些指标可以是响应时间，也可以是前端组件的特性（例如，响应各种移动设备尺寸）。您可以在此处添加用户故事来描述需求。

详细设计

这是设计文档中最长的部分，需要大量的研究、规划和准备。这是解决技术问题的工程方法。

它可以包括伪代码、数据库模式、流程图、线框、组件、输入验证、安全注意事项、API 端点、示例 API 请求/响应以及无数其他内容。

您还可以提及解决问题的替代方法及其权衡。

实施计划

详细设计和实施计划之间可能存在一些重叠，但本节包括完成和交付服务/功能所需的可操作项目（即史诗和任务）。

测试

你会写哪些测试？你如何确保这项服务/功能正常运行？你如何知道这项服务/功能何时停止运行？

运行手册

你们如何推出这项服务/功能？如何监控它？其他人如何排除故障？