提供永久免费的API接口，查看更多API接口，如果您有其他免费API资源，请联系我们，造福人类。

定制开发，免费评估，免费咨询，价格便宜，售后保障，前往开发服务中心或联系开发客服中心

编写技术规范会增加获得成功的项目，服务或所有参与方满意的功能的机会。它减少了在实施过程中甚至在产品启动后出现严重错误的机会。

作为软件工程师，您的主要作用是解决技术问题。您的第一个冲动可能是立即跳入编写代码。但是，如果您还没有考虑完解决方案，那可能是一个可怕的主意。 

您可以通过编写技术规范来思考棘手的技术问题。如果您觉得自己不是一个好作家，写一个人会很沮丧。您甚至可能认为这是不必要的琐事。但是，编写技术规范会增加获得成功的项目，服务或功能，让所有涉众满意的机会。它减少了在实施过程中甚至在产品启动后出现严重错误的机会。 

在本文中，我将带您逐步了解如何编写技术规范以确保产品的性能。  

什么是技术规格文件？

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

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

技术规范为项目中涉及的每个人带来了巨大的好处：编写这些技术的工程师，使用这些技术的团队，甚至是根据其设计的项目。这是为什么您应该写一个的一些原因。 

给工程师带来的好处

通过编写技术规范，工程师被迫在直接进入代码之前检查问题，而他们又可能忽略了解决方案的某些方面。当您分解，整理和安排实施过程中需要做的所有工作时，您可以更好地了解解决方案的范围。技术规格，因为它们是对建议的解决方案的全面了解，因此它们还可以在实施阶段和之后用作项目的文档，以传达您在项目上的成就。 

借助这种经过深思熟虑的解决方案，您的技术规格使您不必重复向多个团队成员和利益相关者解释您的设计。但是没有人是完美的。您的同事和经验丰富的工程师可能会向您展示有关设计，新技术，工程实践，替代解决方案等的新事物，而您以前可能从未见过或未曾想到过这些新事物。他们可能会遇到您可能忽略的解决方案的特殊情况，从而减少了责任。您对规格的关注越多，越好。 

给团队带来的好处

技术规范是在团队和其他利益相关者之间交流项目设计思想的一种直接有效的方法。整个团队可以协同解决问题并创建解决方案。随着越来越多的团队成员和利益相关者为某个规范做出贡献，这使他们在该项目上投入了更多资金，并鼓励他们承担起对该项目的所有权和责任。对于所有人都在同一页面上，它限制了重叠工作可能引起的复杂性。不熟悉该项目的新团队成员可以加入，并为更早的实施做出贡献。  

对项目的好处

投资技术规格最终会生产出优质的产品。由于团队保持一致并就规范需要完成的工作达成了一致，因此大型项目可以更快地进行。规范对于管理复杂性以及通过设置项目限制来防止范围和功能蔓延至关重要。它确定了优先级，从而确保仅将项目中最具影响力和最紧迫的部分放在首位。 

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

编写技术规格书前该做什么

开始之前，请收集问题域中的现有信息。阅读产品团队生产的任何产品/功能要求，以及与项目相关的技术要求/标准。掌握了问题历史记录后，尝试详细说明问题并集思广益，解决您可能认为可以解决问题的各种解决方案。从您提供的所有选项中选择最合理的解决方案。 

请记住，您并不孤单。请经验丰富的工程师作为您的共鸣板，他们对问题有丰富的了解。邀请他们参加会议，并说明问题和您选择的解决方案。布置您的想法和思考过程，并尝试说服他们您的解决方案是最合适的。收集他们的反馈，并请他们成为您的技术规格的审阅者。

最后，是时候实际编写规范了。在您的日历中预留时间来编写技术规范的初稿。使用整个团队都可以访问的协作文档编辑器。获取技术规格模板（请参见下文）并编写粗略的草稿。 

技术规格的内容

当今，许多公司正在解决各种各样的问题。每个组织都是不同的，并创建自己的独特工程文化。结果，即使在公司，部门，团队中，甚至在同一团队的工程师中，技术规范也可能不是标准的。每个解决方案都有不同的需求，您应该根据项目定制技术规格。您无需包括下面提到的所有部分。选择适用于您的设计的部分，然后放弃其余部分。

根据我的经验，技术规范包含七个基本部分：前期事项，简介，解决方案，进一步考虑，成功评估，工作，审议和最终事项。 

1.前沿问题

• 标题 

• 作者

• 球队

• 审稿人

• 创建于

• 最近更新时间

• 史诗，票证，问题或任务跟踪器参考链接

2.简介

一个。概述，问题描述，摘要或摘要

• 问题摘要（从用户的角度），上下文，建议的解决方案和涉众。 

b。词汇或术语

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

C。上下文或背景

• 问题值得解决的原因

• 问题的根源

• 问题如何影响用户和公司目标

• 过去为解决该解决方案所做的努力以及为何无效

• 产品如何与团队目标，OKR相关联

• 解决方案如何适应整体产品路线图和策略

• 解决方案如何适应技术策略

d。目标或产品和技术要求

• 用户故事形式的产品要求 

• 技术要求

 e。非目标或超出范围

• 产品和技术要求将被忽略

F。未来目标

• 产品和技术要求定于未来

G。假设条件

• 要使解决方案按所述方式工作，必须存在并可以访问的条件和资源。 

解决方案

一个。 当前或现有的解决方案/设计

• 当前解决方案说明

• 当前解决方案的利弊

b。建议或提议的解决方案/设计 

• 解决方案将与之交互并改变的外部组件

• 当前解决方案的依赖性

• 拟议解决方案的利弊 

• 数据模型/架构更改

• 模式定义

• 新数据模型

• 修改后的数据模型

• 数据验证方法

• 商业逻辑

• API变更

• 伪码

• 流程图

• 错误状态

• 失败场景

• 导致错误和故障的条件

• 局限性

• 表示层

• 用户要求

• 用户体验的变化

• 使用者介面变更

• 带有描述的线框

• 链接到UI / UX设计器的工作

• 移动问题

• 网络问题

• UI状态

• 错误处理

• 其他要回答的问题

• 解决方案将如何扩展？

• 解决方案的局限性是什么？

• 发生故障时如何恢复？

• 它将如何应对未来的需求？

C。测试计划

• 有关测试如何确保满足用户要求的说明

• 单元测试

• 整合测试

• 质量检查

d。监控和警报计划 

• 测井计划和工具

• 监控计划和工具

• 用于衡量健康的指标

• 如何确保可观察性

• 警报计划和工具

e。发布/推出和部署计划

• 部署架构 

• 部署环境

• 分阶段推出计划，例如使用功能标记

• 计划概述如何将更改传达给用户，例如，使用发行说明

F。回滚计划

• 详细和特定负债 

• 计划减少负债

• 计划描述如何防止其他组件，服务和系统受到影响

G。替代解决方案/设计

• 每个替代解决方案的简短摘要声明

• 每种选择的利弊

• 每种解决方案均无法正常工作的原因 

• 替代方案不如拟议解决方案的方法

• 如果提议的解决方案未能通过，则将计划迁移到下一个最佳替代方案

进一步考虑

一个。对其他团队的影响

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

b。第三方服务和平台注意事项

• 与内部构建服务相比，真的值得吗？

• 与服务/平台相关的安全性和隐私保护有哪些？

• 它要花多少钱？

• 它将如何缩放？

• 预计将来可能出现什么问题？ 

C。成本分析

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

• 推出它要花费什么？ 

d。安全注意事项

• 潜在的威胁是什么？

• 他们将如何缓解？

• 该解决方案将如何影响其他组件，服务和系统的安全性？

e。隐私注意事项

• 解决方案是否遵循有关数据隐私的当地法律和法律政策？

• 该解决方案如何保护用户的数据隐私？

• 解决方案中的个性化和隐私之间有哪些取舍？ 

F。区域考虑

• 国际化和本地化对解决方案有何影响？

• 延迟问题是什么？

• 法律上有什么顾虑？

• 服务可用性的状态如何？

• 如何实现跨区域的数据传输？这里有什么问题？ 

G。辅助功能注意事项

• 解决方案的可访问性如何？

• 您将使用哪些工具评估其可访问性？ 

H。操作上的考虑

• 此解决方案会产生不利的后效应吗？

• 发生故障时如何恢复数据？

• 如果出现故障，解决方案将如何恢复？

• 在为用户带来更高价值的同时，如何保持较低的运营成本？ 

一世。风险性

• 该解决方案正在承担哪些风险？

• 是否存在一旦采取就无法退缩的风险？

• 承担这些风险的成本效益分析是什么？ 

j。支持注意事项

• 支持团队如何在与变更交互时向用户传达有关他们可能面临的常见问题的信息？

• 我们如何确保用户对解决方案感到满意，并可以在最少的支持下与之交互？

• 谁负责解决方案的维护？

• 如果项目所有者不可用，如何完成知识转移？ 

成功评估

一个。影响力

• 安全影响

• 性能影响

• 成本效应

• 对其他组件和服务的影响

b。指标

• 要捕获的指标列表

• 捕获和衡量指标的工具

工作

一个。工作估算和时间表

• 特定，可衡量和有时间限制的任务列表

• 完成每项任务所需的资源

• 每个任务需要完成多长时间的时间估算

b。优先次序

• 按紧迫性和影响对任务进行分类

C。大事记

• 注明日期的检查点，表示将完成大量工作

• 指示里程碑已过的指标

d。未来的工作

• 将来将要完成的任务清单

审议

一个。讨论区

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

b。公开问题

• 关于事情的问题，您不知道答案或不确定您会向团队和利益相关者提出建议。这些可能包括您尚不知道如何解决的问题。 

结束事项

一个。相关工作

• 提议的解决方案外部的，与该解决方案类似的所有工作，并且由不同的团队进行。了解这一点很重要，以便在遇到相关问题时能够在这样的团队之间共享知识。 

b。参考文献

• 链接到您在设计时想使用的文档和资源。 

C。致谢

• 赞扬对您希望认可的设计做出过贡献的人们。

编写技术规范后

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

彻底检查后，将草案发送给您的团队和利益相关者。尽快解决所有评论，问题和建议。为每个问题设置截止日期。安排会议以讨论团队划分的问题或对该文件进行的冗长讨论。如果即使在举行了面对面的会议以解决问题后，团队仍未能就某个问题达成共识，请在最终解决该问题时与您联系，以最终决定。要求不同团队的工程师检查您的规范，以便您了解局外人的观点，这将增强其如何影响与团队无关的利益相关者。即使在实施过程中，在设计，进度，工作估算，范围等方面进行任何更改也可以更新文档。

结论

编写测试规范可能是确保项目成功的有效方法。稍加规划和一些前瞻性就可以使项目的实际实施变得更加容易。  

2023-03-22 10:04:19