技术需求文档，应当这么写

需求文档是我们在开发中常用的一类沟通方式和媒介，它承载着需求方的期望，同时也标记着一系列事项的生命周期。

不同部门、不同受众的需求文档各异，例如运营人员向产品人员提出的活动需求、产品人员向开发人员提出的功能需求、开发人员向运维人员提出的服务支撑需求、各小组内部同事之间互相提出的需求等等。

为何需要需求文档？

大部分场景下需求提出方和需求承接方都存在不小的信息差，需求提出方常用的语句是“我需要做成这样”、“越快越好”、“怎么用你不用管，给我就行”、“这不是我想要的”、“我想要的其实是那样”。

一个人经常否定自己的选择和言语的现象是存在的，无论有意或无意，但这无疑会耗费双方的时间和精力。需求文档不仅可以作为双方沟通过程中的清单，还可以作为双方选择和执行的日志，有了需求文档，就能够避免因前后矛盾导致空耗的问题。同时，需求文档可以清晰地体现参与人员的劳动成果与劳动价值，是自我总结的良好依据。

需求文档通用模板参考

一百种需求有一千种提法，但需求中的事项相差却无几。这里给出了一份需求文档模板，大家可以将其用在工作当中，作为不同人员之间的信息传递媒介。

要注意的是，需求和执行是双生相伴的，因此这里的下面这份参照文档与其说是需求文档，不如说是任务执行记录，因为它记录着这个任务从产生到执行完毕的完整生命周期。

为了方便大家理解，文档选用不同颜色来帮助我们区分阶段，其中：

🔲 浅粉色区块呈现的是文档的基本信息；

🔲 浅蓝色区块呈现的是需求主体与需求生命周期主体；

🔲 浅绿色区块呈现的是需求生命周期接近末尾，即将达成目的；

为什么要这么设计？

相信各位见过不少的需求文档，因此对上面这份参考也有不同的看法，可能不禁会问：

• 为什么设计成这样的结构？
• 怎么不用在线需求文档管理工具呢？
• 必填项和非必填项如何体现？
• 这份参考好像不能满足所有开发场景？

为什么设计成这样的结构？

需求文档应当涵盖从需求产生到需求完成交付的完整过程，例如需求是在什么样的场景下产生的、到底要做成什么样、需要什么时候完成、以什么形式交付、需求是否能够实现、需求实现过程中做了哪些、交付的结果是否达到预期等。

我们可以将完整过程分为以下几个阶段，以便更好地展开工作：

🔲 需求描述

🔲 需求调研

🔲 需求评审

🔲 开发 /实施

🔲 阶段验收

🔲 测试 /数据验证

🔲 上线

按照这个结构，我们能够想象工作流大抵如下：

首先需求提出方给出需求的背景、具体事项描述等信息，帮助需求承接方更好地理解，同时提出对交付时间、交付方式的期望。需求承接方收到需求信息后需要做初步的调研，了解需求实现过程中的关键项并记录不明确的事项。

接着，双方初步接触后约定时间对需求进行评审，双方的讨论将基于调研期间获得的信息展开，在评审讨论会结束后通常会确定需求是否能实现、需求改动项、交付方式、交付时间、最终参与人员等。

然后评审通过，需求承接方开始进行开发 /实施。需求承接方要记录这个过程中谁在什么时间做了什么事并得到怎样的结果、期间是否出现了哪些变化。

需求提出方可能会阶段性地跟进事件进展，并帮助需求承接方确认工作和工作结果没有出现偏差，同时双方互换一些信息。

开发 /实施接近尾声或完成后，需求方组织人员检验成果，检验通过则通知需求承接方交付 /发布上线，检验未通过则做相应调整。

版权水印 - 微信公众号 Python 编程参考

除了需求背景、开发 /实施相关的信息外，需求文档本身也需要提供一些基础属性，用以对需求进行整理、分类、追溯、总结等，所以在需求文档的开头设定了一些重要信息栏，例如：

🔲 需求重要等级；

🔲 需求发起日期；

🔲 需求完结日期；

🔲 需求发起人及对应部门；

🔲 需求承接人及对应部门；

🔲 需求所属的业务类型；

🔲 需求关键词；

🔲 也求所属业务的名称；

🔲 需求关注者；

🔲 需求编号；

🔲 需求名称；

团队内部可以定义统一的需求等级，例如紧急且重要的设为 A、紧急但不重要的设为 B1、重要但不紧急的设为 B2、不重要也不紧急的设为 C 等，这样大家在参与需求的时候能够合理地分配时间和资源，优先解决那些等级高的需求。

怎么不用在线需求文档管理工具呢？

市面上的需求文档管理工具繁多，Python 编程参考希望在不依赖特定工具的情况下向大家介绍需求文档，各位在理解需求文档后再结合工作中用到的管理工具，效率定会更高。

实际上工作中总是会用到各式各样的管理工具，工具可以很好地帮助我们关联文档、汇总信息。例如一个编号为 TK2020120101 的需求完成后，后续又衍生出针对它的维护类需求 TK2021010103 时，可以将维护类需求 TK2021010103 与 TK2020120101 关联起来，这样在管理需求文档的时候就能够直观地看到需求之间的关系和变化，具体如下图所示。

实际工作中大概率会用到管理工具，工具可以提高我们的效率，便于我们管理事件，借助工具是非常好的选择

必填项和非必填项如何体现？

实际上这份文档包含的区块都是必要信息，但区块中的子项可以根据实际情况省略。

首先，浅粉色区块的需求文档基础信息部分是必填的，这里的内容是整个需求的缩影，所以一个格子也不能少。

其次，浅蓝色区块的主体部分是可以省略的，例如有时候需求调研和需求评审可以放在同一时间展开，划分到需求评审即可；例如子项详细描述中的注意事项、交付要求等选项也是可以根据实际情况省略的；如果需求并不复杂，或者说时间周期也不长，那么子项阶段验收可以省略，在数据验证阶段校验即可；如果没有预上线，或者需求并不需要上线，那么可以省略浅绿色区块部分的项。

最后，如果觉得上面的阶段还不足以记录完整的需求生命周期，可以根据实际情况增加阶段或子项；

这份参考好像不能满足所有开发场景？

当然，开发场景千千万万，Python 编程参考提供的这份需求文档作为基础，各位在具体使用的时候可以根据团队情况和业务情况自行调整文档项。

需求文档实例参考

虽然上面提供了一份基础模板，但是有一些读者可能还不太明白在实际使用的时候应该如何编写。下面以实际的工作需求给出一份实例参考。

阅读并吸收上面的知识后，想必聪明的你对整个需求文档的构成、设计考量和具体实践有了一定的认知，现在已经能够很好地梳理、组织需求文档了。这里作者再帮助诸位整理一下需求文档的一些细节。

需求调研研究的是什么？

需求调研是基于需求展开的实际情况探索，主要诉求是得出是否、能否等确切的结论；例如参考实例中提到的：

🔲 当前线上 Nginx 配置文件是否需要改动；

🔲 调用方是否要在更换新 Nginx 后切换调用地址；

🔲 线上服务地址权限是否能顺利获得；

需求评审讨论什么？

需求评审基于调研结果和需求背景展开，主要诉求是得出实现方式、结果、呈现方式等确切的结论，并针对那些不稳定的事项给出结果，同时也包含是否、能否等确切结论，例如：

🔲 评审项：监控项与可视化面板是否匹配；

🔲 评审结果：监控项与可视化面板匹配，但要设定告警则需要单独设置面板，不影响展示；

开发实施记录哪些内容？

开发 /实施项中不必记录细节，只需要记录阶段性内容即可。通常是谁在什么时间完成了什么事，也就是 [时间][人][事件] 这样的格式，例如参考实例中记录的：

🔲 [2020-12-01][数据采集][张三] - 提供 Nginx 配置文件；

🔲 [2020-12-05][运维][王五] - 在 Grafana 中导入 Prometheus 数据源并配置可视化面板；

🔲 [2020-12-07][运维][王五] - 更改域名解析；

阶段验收写什么？

阶段验收关注的是事件结果，也就是 [时间][人][结果] 这样的格式，与开发 /实施记录类似，例如参考实例中记录的：

🔲 [2020-12-08][数据采集][张三] - 服务切换后一切正常；

🔲 [2020-12-06][数据采集][张三] - Grafna 可视化面板数据；

🔲 [2020-12-03][数据采集][张三] - Nginx 日志已同步到 ElasticSearch 中；

上线项关注什么？

上线项关注的是上线结果和业务本身的状态，是 [时间][人][状态] 这样的格式，例如参考实例中记录的：

🔲 [2020-12-09][运维][王五] - 服务正常正常；

🔲 [2020-12-09][数据采集][张三] - 数据正常；

🔲 [2020-12-09][测试][李四] - 数据正常；

这里的状态也可以理解为结果，但细细想来，还是用状态更为贴切一些。

不知道你们公司的需求文档是什么样的，欢迎在评论区留言讨论 🎉🎉🎉

点击前往作者韦世东的技术专栏 www.weishidong.com，看更多有用知识。热门文章一览

《几个有效应对 35 岁危机的办法》

《工程师绘图与设计实践指南》

《持续交付实践 - GitHub Actions 部署 Node 应用到云服务器》

《 SSH 免密码 /免用户名 /免 IP 登录云服务器实践》

《 ElasticSearch 定时删除指定天数的数据实践》