作为一名软件工程师，你的主要职责是解决技术问题。你的第一个冲动可能是立即直接开始编写代码。但如果你没有仔细考虑过你的解决方案，那么这可能是一个糟糕的主意。

你可以通过编写技术规范来思考一些困难的技术问题。如果你自认并非一个好作家，那么编写这样的技术规范可能会让你感到沮丧。你甚至可能认为这是一件不必要的琐事。但是，编写技术规范真的可以增加成功的项目、服务或功能的机会，让所有利益相关者都感到满意。它可以降低在实施过程中甚至在产品发布之后出现严重错误的几率。

在本文中，我将讲述如何编写确保产品质量的技术规范。

什么是技术规范文档

技术规范文档概述了如何通过设计和构建解决方案来解决技术问题。它有时也被称为技术设计文档、软件设计文档或工程设计文档。它通常是由工程师编写的，他们将构建解决方案或在实施过程中担任负责人，但对于大型项目，它可以由技术负责人、项目负责人或高级工程师编写。这些文档向工程师团队和其他利益相关者展示了功能、项目、计划和服务的设计、所涉及的工作、影响和时间线。

为什么编写技术规范很重要

技术规范对参与项目的每个人都有巨大的好处：编写它们的工程师，使用它们的团队，甚至是根据它们设计的项目。以下是你应该编写技术规范的一些理由。

给工程师带来的好处

通过编写技术规范，工程师被迫在直接进入代码之前检查问题，在代码中他们可能会忽略解决方案的某些方面。当你把实施过程中需要做的所有工作进行分解、组织和安排，你就会对解决方案的范围有一个更好的认识。因为技术规范是所提议的解决方案的透彻看法，所以技术规范也可以作为项目的文档，无论是在实施阶段还是实施之后的文档，都是为了交流你在项目上的成就。

有了这个经过深思熟虑的解决方案，你的技术规范就不必再向多个团队成员和利益相关者反复解释你的设计了。但常言道，人无完人。你的同行和经验更为丰富的工程师可能会给你展示他们在设计、新技术、工程实践、替代解决方案等方面的新事物，而这些你以前可能从未见过或从未想到过。他们可能会发现你可能忽略的解决方案的例外情况，从而减少你的责任。反正你编写的技术规范，关注的人越多越好。

给团队带来的好处

要在团队和其他利益相关者之间沟通项目设计思想，技术规范是一种直接而有效的方式。整个团队可以协作解决问题并创建解决方案。随着越来越多的团队成员和利益相关者为规范做出贡献，这会让他们在项目中投入更多精力，并鼓励他们主动承担责任，并为之负责。由于每个人都有相同的想法，它限制了重叠工作可能产生的复杂性。不熟悉该项目的新团队成员可以自己加进来，并提前为项目的实施做出贡献。

给项目带来的好处

对技术规范的投资最终会带来卓越的产品。由于团队是一致的，并且就需要通过规范完成的工作达成一致，因此大型项目可以进展得更快。规范对于管理复杂性和通过设定项目限制来防止范围和功能蔓延方面是必不可少的。它设定了优先级，从而确保项目中只有影响最大、最紧迫的部分才会被优先考虑。

项目实施后，它有助于解决项目中出现的问题，并为回顾和事后总结提供见解。最好的计划规范可以作为衡量工程成功与否和工程时间投资回报的最佳指南。

编写技术规范之前要做什么

在开始之前，请收集问题域中的现有信息。阅读产品团队提出的任何产品 / 功能要求，以及与项目相关的技术要求 / 标准。在了解问题的来龙去脉后，试着详细地陈述问题，并进行头脑风暴，想出各种你认为可能会解决的解决方案。从你想出的所有方案中选出一个最合理的解决方案。

记住，你并不是一个人在执行这项任务。请一位对这个问题很有经验的工程师做你的参谋。邀请他们参加会议，并说明问题和你选择的解决方案。列出你的想法和思考过程，并试图说法他们相信你的解决方案是最合适的。收集他们的反馈，并请他们为你的技术规范进行审查。

终于到了真正编写技术规范的时候了。在你的日程表中留出时间用来编写技术规范的初稿。使用整个团队都可以使用的协作文档服务。获取技术规范模板（见下文），并写一份粗略的草案。

技术规范的内容

今天，许多公司都在解决各种各样的问题。每个组织都是独一无二的，并创造了自己独特的工程文华。因此，即使在公司、部门、团队内部，甚至在同一团队的工程师之间，技术规范也可能不是标准的。每个解决方案都有不同的需求，你应该根据项目来定制你的技术规范。你并不需要包括下面提到的所有部分。选择适合你的设计部分，然后放弃其他部分。

根据我的经验，技术规范包括以下七个基本部分：

前页、简介、解决方案、其他考虑因素、成功评估、工作、审议和结文。

前页

1、题目

2、作者

3、团队

4、审核人

5、编写日期

6、最后更新日期

7、Epic（史诗故事）、Ticket（凭据）、发布、任务追踪器参考链接

简介

1、概述、问题描述、总结或摘要

• 问题摘要（从用户的角度）、上下文、建议的解决方案和利益相关者。

2、词汇表或术语表

• 你在研究设计时遇到的新术语，或者你可能怀疑读者 / 利益相关者不知道的术语。

3、上下文或背景

• 问题值得解决的原因。
• 问题的根源。
• 这个问题如何影响用户和公司目标。
• 过去为解决这一问题所做的努力及其无效的原因。
• 产品如何与团队目标和关键成果相关。
• 解决方案如何融入整个产品路线图和战略。
• 解决方案如何融入技术战略。

4、目标或产品与技术要求

• 以用户故事的形式提出产品需求。
• 技术要求。

5、非目标或超出范围

• 不予考虑的产品和技术要求。

6、未来目标

• 未来的产品和技术要求。

7、假设

• 需要具备并可获得的条件和资源，以使解决方案如上所述发挥作用。

解决方案

1、现时或现有的解决方案 / 设计

• 当前解决方案说明。
• 当前解决方案的优缺点。

2、建议或提议的解决方案 / 设计

• 解决方案将与之交互并进行更改的外部组件
• 当前解决方案的依赖项
• 建议的解决方案的优缺点
• 数据模型 / 模式变化。

​ a、模式定义

​ b、新的数据模型

​ c、修改后的数据模型

​ d、数据验证方法

• 业务逻辑

​ a、API 变化

​ b、伪代码

​ c、流程图

​ d、错误状态

​ e、失败场景

​ f、导致错误和失败的条件

​ g、局限性

• 表示层

​ a、用户需求

​ b、用户体验变化

​ c、用户界面变化

​ d、带描述的线框图

​ e、链接到用户界面 / 用户体验设计器的工作

​ f、移动关注点

​ g、Web 关注点

​ h、用户界面状态

​ i、错误处理

• 其他需要回答的问题

​ a、该解决方案将如何扩展？

​ b、该解决方案的局限性是什么？

​ c、一旦发生故障，它将如何恢复？

​ d、它将如何应对未来的需求？

3、测试计划

• 解释测试如何确保用户需求得到满足的说明
• 单元测试
• 集成测试
• 质量保证

4、监控和警报计划

• 日志计划和工具
• 监控计划和工具
• 用于衡量运行状况的指标
• 如何保证可观测性
• 警报计划和工具

5、发布 / 推出和部署计划

• 部署架构
• 部署环境
• 分阶段推出计划，例如使用功能标志。
• 计划概述如何向用户转达更改，例如，使用发行说明。

6、回滚计划

• 详细和具体的负债。
• 减少负债的计划。
• 描述如何防止其他组件、服务和系统受到影响的计划。

7、替代解决方案 / 设计

• 每个替代解决方案的简短摘要说明
• 每种替代解决方案的利弊
• 每种解决方案均无法正常工作的原因
• 替代方案在哪些方面不如建议的解决方案
• 在建议的方案失败的情况下，向次佳次佳替代方案迁移的计划

其他考虑因素

1、对其他团队的影响

• 这将如何增加其他人的工作？

2、第三方服务和平台考虑因素

• 与内部构建服务相比，这真的值得吗？
• 与服务 / 平台相关的安全和隐私问题有哪些？
• 总共要花多少钱？
• 它将如何扩展规模？
• 预计未来可能会出现哪些问题？

3、成本分析

• 每天运行解决方案的成本是多少？
• 推出它的成本是多少？

4、安全方面考虑因素

• 潜在的威胁是什么？
• 如何减轻这些风险？
• 该解决方案将如何影响其他组件、服务和系统的安全性？

5、隐私方面考虑因素

• 该解决方案是否遵循有关数据隐私的当地法律和政策？
• 该解决方案如何保护用户的数据隐私？
• 在解决方案中，个性化和隐私之间有哪些权衡？

6、地区性考虑因素

• 国际化和本地化对解决方案有什么影响？
• 延迟问题是什么？
• 在法律上有什么顾虑？
• 服务可用性的状态是什么？
• 如何实施跨地区的数据传输？这方面需要关注的问题是什么？

7、可访问性考虑因素

• 解决方案的可访问性如何？
• 你将使用那些工具来评估其可访问性？

8、运营方面考虑因素

• 这种解决方案是否会产生不良后果？
• 一旦发生故障，如何恢复数据？
• 如何在为用户带来更高价值的同时保持较低的运营成本？

9、风险性

• 该解决方案存在哪些风险？
• 是否有一些风险一旦承担就无法挽回？
• 承担这些风险的成本效益分析是什么？

10、支持方面考虑因素

• 在于更改交互时，支持团队将如何向用户传达有关他们可能面临的常见问题的信息？
• 我们如何确保用户对解决方案感到满意，并且能够在最少的支持下与之交互？
• 谁负责解决方案的维护？
• 如果项目所有者不在，如何完成知识转移？

成功评估

1、影响

• 安全影响
• 性能影响
• 成本影响
• 对其他组件和服务的影响

2、指标

• 要捕获的指标列表
• 用户捕获和度量指标的工具

工作

1、工作估算和时间表

• 具体的、可衡量的和有时限的任务列表。
• 完成每项任务所需的资源。
• 每项任务需要完成的时间估算。

2、优先次序

• 按紧急程度和影响对任务进行分类。

3、里程碑

• 当大量的工作已经完成时，标注有日期的检查点。
• 表明里程碑通过的衡量标准。

4、未来的工作

• 将来要完成的任务列表。

审议

1、答辩

• 团队成员不同意解决方案的内容，需要进一步辩论，以达成共识。

2、待决问题

• 向团队和利益相关者提出一些你不知道答案或不确定的问题，以征求他们的意见。这些可能包括你还不知道如何解决的问题的各个方面。

结文

1、相关工作

• 在某种横渡上与建议的解决方案相似，且由不同团队处理的任何外部工作。
• 了解这一点很重要，当遇到相关问题时，这样的团队之间能够实现知识共享。

2、参考文献

• 指向参考文档和资源的链接，这些参考文档和连接是你在设计时进行参考的内容。

3、致谢

• 致谢那些为你希望认可的设计做出过贡献的人们。

完成编写技术规范之后

现在，你已经编写好了规范，是时候对其进行完善了。像一个独立的审稿人一样，仔细审阅你的草案。问问自己设计的哪些部分不清楚，哪些部分不确定。修改草案，把这些问题包括进去。再次检查草案，就好像你的任务仅仅是根据技术规范来实施设计一样。确保规范是一个足够清晰的实施指南。如果你不在的话，团队可以按照这份指南进行工作。如果你对解决方案有疑问，并且想要对它进行测试以确保有效，那么可以创建一个简单的原型来证明你的概念。

当你完成彻底审阅后，将草案发给你的团队和利益相关者。尽管处理所有的意见、问题和建议。为每个问题设定最后期限。安排会议，讨论团队在那些问题上存在分歧，或者对文档进行一场冗长的讨论。如果团队在某个问题没有达成一致，即使在进行了面对面的会议之后，也要做最后的决定，因为责任就落在你身上了。要求不同团队中的工程师审查你的规范，这样你就可以从局外人的角度出发，从而加强对非团队成员的利益相关者的了解。即使在实施过程中，也要用设计、进度、工作估算、范围等方面的任何变更来更新文档。

结论

编写测试和规范是保证项目成功的有效方法。稍作规划和稍作深思熟虑就可以使项目的实际实施变得轻松许多。

作者 | Zara Cooper 译者 | Sambodhi 编辑 | Natalie