V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
vansenb
V2EX  ›  程序员

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

  •  1
     
  •   vansenb · 2021-02-18 20:13:42 +08:00 · 3751 次点击
    这是一个创建于 1374 天前的主题,其中的信息可能已经有所发展或是发生改变。

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

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

    为何需要需求文档?

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

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

    需求文档通用模板参考

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

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

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

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

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

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

    为什么要这么设计?

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

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

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

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

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

    🔲 需求描述

    🔲 需求调研

    🔲 需求评审

    🔲 开发 /实施

    🔲 阶段验收

    🔲 测试 /数据验证

    🔲 上线

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

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

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

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

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

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

    版权水印 - 微信公众号 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 定时删除指定天数的数据实践》

    17 条回复    2021-02-20 16:54:18 +08:00
    YouLMAO
        1
    YouLMAO  
       2021-02-18 20:44:30 +08:00 via Android   ❤️ 1
    光看你需求等级是 abc,不是 p0,p1 就知道你不是 bat 的,瞬间没看完
    learningman
        2
    learningman  
       2021-02-18 20:49:15 +08:00
    单链表反转都不会就能面阿里巴巴的吗
    这也太。。。。
    vansenb
        3
    vansenb  
    OP
       2021-02-18 21:13:15 +08:00
    @YouLMAO ABC 也好,P0123 也好,都是为了表示重要紧急程度,团队内部设定的代号,写 P 就一定厉害吗?
    vansenb
        4
    vansenb  
    OP
       2021-02-18 21:13:44 +08:00
    @learningman 是啊,所以这不就没通过吗
    Lemeng
        5
    Lemeng  
       2021-02-18 21:16:30 +08:00
    有点长。很详细
    YouLMAO
        6
    YouLMAO  
       2021-02-18 21:30:16 +08:00 via Android
    @vansenb 意思是尽量向大厂借鉴,举个例子,街头煎饼果子说我要拿米其林三星,我的收费要比北京国宴总厨高,至少你要先尝尝三星的饭菜
    leonme
        7
    leonme  
       2021-02-18 21:30:48 +08:00 via iPhone
    @vansenb 主要是技术名词对齐,减少沟通成本 2333
    vansenb
        8
    vansenb  
    OP
       2021-02-18 21:34:39 +08:00
    @YouLMAO 你这里的例子不恰当,不过意思我明白了。我要写成 P,万一评论区又有人说干嘛不写 ABC 呢,简单直观。我看你也不是故意吐槽的,和谐一些。
    humansjl
        9
    humansjl  
       2021-02-19 02:42:12 +08:00
    提问楼主,这份文档由哪个岗位的人主导编写呢?
    vansenb
        10
    vansenb  
    OP
       2021-02-19 08:52:41 +08:00
    @humansjl 技术需求文档是给开发者看的,由技术部门的负责人主导是优选。写完一个版本后可以叫上产品互通一下,后续要求技术和产品强制执行,就能够落地了。
    GM
        11
    GM  
       2021-02-19 09:23:50 +08:00
    图裂了
    stevenkang
        12
    stevenkang  
       2021-02-19 10:15:35 +08:00
    “团队内部可以定义统一的需求等级”

    于是明明有 P0 、P1 、P2... 统一的优先等级不用,我们重新创造一个 A 、B1 、B2...

    有点迷惑,这到底是为了统一团队的名词理解,还是为了啥。建议造名词前先了解行业惯例,避免增加额外的名词理解负担。

    另搜索了一下:P=priority
    jmyz0455
        13
    jmyz0455  
       2021-02-19 10:20:34 +08:00
    好东西。
    stupil
        14
    stupil  
       2021-02-19 11:51:58 +08:00
    用户层面的需求和技术层面的需求不是一个概念。
    首先要定义一下,这是谁写的需求文档,产品还是技术?
    另外,需求是那个层面的,用户需求、开发需求还是运维需求?

    例如: 当前线上 Nginx 配置文件是否需要改动

    如果是后端需求,不满足是否会造成业务需求的不满足?
    vansenb
        15
    vansenb  
    OP
       2021-02-19 13:06:16 +08:00   ❤️ 1
    @stevenkang 既然知道 Priority,也知道 P0 、P1 、P2,那团队内部就选用这个就好了。灵活变通一下,不要杠。
    vansenb
        16
    vansenb  
    OP
       2021-02-19 13:07:20 +08:00
    @stupil 这个只是参考模板,具体的可以按照自己公司的业务进行调整。不是说这一套可以满足所有场景,仔细看一下文章哈
    stupil
        17
    stupil  
       2021-02-20 16:54:18 +08:00
    所以对你们的场景 你应该叫事务或者任务管理。

    提出所需要的任务,任务的目的 和期望的结果,以及外围相关的(任务类型、任务相关人等)
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   1971 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 23ms · UTC 00:48 · PVG 08:48 · LAX 16:48 · JFK 19:48
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.