如何撰写需求文档

永远考虑那个拥有更强写作能力的人

  如果一个岗位有几个候选人，永远考虑那个拥有更强写作能力的人。无论这个人是设计师、程序员、市场或销售人员，写作能力总是可以带来回报的。有效、简洁的写作能带来有效、简洁的代码、设计、邮件、即时通讯等等。

  写作带来：
更深度的思考，更认真的生活，更清晰的沟通，更有效的社交， 更强大的内心。

工欲善其事,必先利其器

君子生非异也，善假于物也

  思想固然重要,但是善于借助工具表达自己的思想也很重要。这里介绍一些好用的写作方面的工具。

Markdown

  根据 百度百科-markdown,Markdown是一种轻量级标记语言，创始人为约翰·格鲁伯（英语：John Gruber）。 它允许人们使用易读易写的纯文本格式编写文档，然后转换成有效的XHTML（或者HTML）文档。

  Markdown是一种简单的格式化文本的方法，让排版变得简答,在任何设备上看起来都很棒。有道笔记,印象笔记,博客园,vscode,github,码云等都支持markdown语法。

  相关教程

• Markdown编辑器教程。

• 想学 Markdown？这篇文章帮你快速上手。

思维导图

  对于某些需求涵盖功能点较多,后者分支较多场景,使用思维导图呈现更直观。比如,这是我整理的考试系统的前期需求的一个思维导图：

  现在有很多工具都支持画思维导图:

• processon
• xmind
• 百度脑图

流程图

  程序员童鞋对流程图肯定不会陌生,常见程序流程图设计应该是信手拈来。针对复杂需求,有时候使用语言和文字难以描述清楚。这个时候,流程图该上场了。

  流程图在整个需求的整理中的核心,他能将产品业务背后的逻辑展示出来。这个需要你对吃透需求,然后内化,加工,再输出。说句题外话,如果你参与了这个需求,一定要抠细节,流程越细化,越有助于成功的实现需求。。

  这里推荐几个常用的流程图工具：

• processon
• Edraw
• draw.io【开源】

换位思考

接到需求之后,技术同学往往会先思考技术实现,然后陷入技术细节,这也是大多数技术人的通病。

  在此前的文章 《需求管理》中,我曾指出技术同学要放下傲慢和偏见,跳出技术思维。这对于需求的理解和整理至关重要。

  跳出技术思维,然后换位思考,这有助于全方位,多角度的理解需求。一个功能可能由不同的角色人员使用,视角不同,需求不同。你需要像导演拍电影一样,针对不同角色，一个场景一个场景的拍摄,最终串联成一个完整的电影作品。

这个需求,「不做」

懂得拒绝是一门艺术。

  技术人不是一个没有灵魂的代码工具。“这是需求爸爸提的,我没法拒绝”,“这是产品爸爸喊做的,不管我的事”。当出现问题的时候,我们经常听到技术同学这样说。

  不合理的需求,对用户不友好的需求,低收益,高投入的需求,要敢于拒绝。当然,拒绝也是一门艺术,这就是与人沟通的艺术。如果经过深思熟虑,你能够给出比较合理的解释或者提出更有建设性的方案,我想这样才会更加容易让人接受。

闭环

闭环这个词,真是互联网领域的万金油。但是,笔者这里特指产品需求逻辑的闭环。

  笔者曾经待过一个互联网教育创业公司。因为参与人很多都是TOB行业经验的人。大家都是知道,TOB公司的产品卖出去很多时候是线下的操作。比如,微软公司,我做操作系统一流,我赢家通吃。但是,TOC就不一定了,个体用户更加注重用户体验,比如曾经的电商百团大战的竞争,后面的共享单车的竞争,消费者可以直接用脚投票的。

  我们做了一个课程官网,包括课程展示,订阅充值的官网。官网上线之后,市场同事也做了宣传,但是发现基本上没人注册,很多用户都是让我们帮忙注册。经过研究发现了原因:

• 因为集成Azure注册慢,登录页面,而且极不友好。 这导致用户放弃注册。
• 官网没有展示客服咨询电话,只有一个用户建议表单。无法实时联系客服。

  这个案例,很典型。从市场到技术,我们做了很多工作,但是最终效果不理想。**最大的愿意就是产品不闭环。**用户想学习课程,但是登录和注册体验太差,这就已经挡住了大部分的用户。

写作套路

  前面我们讲了很多坑和避坑策略,那要如何才能写好需求文档呢？

铺垫

根据 百度百科-铺垫法。戏剧情节结构的一种手法。在戏剧的进展中，对于某些将要出现的关键性情节和起关键作用的人物，必须在事前有所准备、暗示；为情节的展开，为高潮的到来，酝酿气氛，作好准备，铺平道路。这种手法叫埋伏或伏笔。

  其实可以简单理解为背景说明。在需求文档中,增加一定的背景表述,可以增强事物间的因果联系和完整性,不显突兀。

  一般可以在你的需求前增加一个背景交代，

  这样的好处是,其一,让之前没有参与的人有个背景认识;其二,为自己后续的观点(或者设计思路)提供可信依据,至少不知自己拍脑袋想出来的。

下定义

  对于不同的业务,有时候会有一些专有名词,或者是你自己了说明某个事物而定义的名词。如果不做一些定义的解释,很难理解。比如,在设计IM聊天时候,可能会有一些定义,可以给出定义。

逻辑清晰

  需求文档,不是日记,切记流水账。排版工整,重难点突出。逻辑清晰,富有层次感。

  利用图表配合文字,有条不紊的表达出合理地逻辑。这样大家阅读起来,一目了然。

说人话

针对不同的人群一定要设计不同的话术

  这里的人是指不同的受众。考虑到需求文档面向的对象较多,有技术,业务,测试等,需要抛弃过于专业的技术语言，比如不要出现技术设计的细节,尽量要用自然语言表达。

  说句题外话,其实严格意义上,需求文档可能是要写两份,一类是给技术同学看的,一类是给非技术同学看的。对于前者,你当然可以用类似抽象的uml图或者直接给出伪代码来说明。

视角

子非鱼,安知鱼之乐

  你以为的就是你以为的吗?很多时候,需求的来源并不单一,比如公司要做一个工单系统,这个工单系统的使用者几乎涵盖了公司的各个部门。按照"用户第一"的要求,我们需要考虑到不同业务方的诉求和用户习惯。

  我们在做需求的时候,就要提前想到。否则,后面的设计一定会违背使用者的意图。前面,讲过的换位思考,或者多角色思考该排上用场了。

  在文档中,如何体现呢？通常,可以按照不通视角来描述。这就是类似程序的switch…case…

  切记站在上帝视角看待问题。

版本延续性

  需求文档很少一次性就让各方满意的,或多或少都会有补充和调整。比较好的习惯是使用修订版本来记录。

  修订历史是一个版本的可追溯源，对需求变更历程有一个清晰的认识。

  新建默认为相应模块的首次使用，对于文档的修改以及增加的地方可加入超链接，同时在增加与修改的具体地方进行颜色标示或者其他标志来进行区分，方便其他人员进行查询。

结语

  写好一个需求文档,让人觉得很专业有很多东西需要学习。这里笔者只根据个人多年的工作经验,抛砖引玉,欢迎大家怕批评和斧正。

如何撰写需求文档

• 永远考虑那个拥有更强写作能力的人
• 工欲善其事,必先利其器
  • markdown
  • 思维导图
  • 流程图
• 换位思考
• 这个需求,「不做」
• 闭环
• 写作套路
  • 铺垫
  • 下定义
  • 逻辑清晰
  • 说人话
  • 视角
  • 版本延续性
• 结语

Reading makes a full man, conference a ready man, and writing an exact man.

本文节选自《Springboot实战纪实-如何撰写需求文档》,阅读时长3min。

永远考虑那个拥有更强写作能力的人

  如果一个岗位有几个候选人，永远考虑那个拥有更强写作能力的人。无论这个人是设计师、程序员、市场或销售人员，写作能力总是可以带来回报的。有效、简洁的写作能带来有效、简洁的代码、设计、邮件、即时通讯等等。

  写作带来：
更深度的思考，更认真的生活，更清晰的沟通，更有效的社交， 更强大的内心。

工欲善其事,必先利其器

君子生非异也，善假于物也

  思想固然重要,但是善于借助工具表达自己的思想也很重要。这里介绍一些好用的写作方面的工具。

Markdown

  根据 百度百科-markdown,Markdown是一种轻量级标记语言，创始人为约翰·格鲁伯（英语：John Gruber）。 它允许人们使用易读易写的纯文本格式编写文档，然后转换成有效的XHTML（或者HTML）文档。

  Markdown是一种简单的格式化文本的方法，让排版变得简答,在任何设备上看起来都很棒。有道笔记,印象笔记,博客园,vscode,github,码云等都支持markdown语法。

  相关教程

• Markdown编辑器教程。

• 想学 Markdown？这篇文章帮你快速上手。

思维导图

  对于某些需求涵盖功能点较多,后者分支较多场景,使用思维导图呈现更直观。比如,这是我整理的考试系统的前期需求的一个思维导图：

  现在有很多工具都支持画思维导图:

• processon
• xmind
• 百度脑图

流程图

  程序员童鞋对流程图肯定不会陌生,常见程序流程图设计应该是信手拈来。针对复杂需求,有时候使用语言和文字难以描述清楚。这个时候,流程图该上场了。

  流程图在整个需求的整理中的核心,他能将产品业务背后的逻辑展示出来。这个需要你对吃透需求,然后内化,加工,再输出。说句题外话,如果你参与了这个需求,一定要抠细节,流程越细化,越有助于成功的实现需求。。

  这里推荐几个常用的流程图工具：

• processon
• Edraw
• draw.io【开源】

换位思考

接到需求之后,技术同学往往会先思考技术实现,然后陷入技术细节,这也是大多数技术人的通病。

  在此前的文章 《需求管理》中,我曾指出技术同学要放下傲慢和偏见,跳出技术思维。这对于需求的理解和整理至关重要。

  跳出技术思维,然后换位思考,这有助于全方位,多角度的理解需求。一个功能可能由不同的角色人员使用,视角不同,需求不同。你需要像导演拍电影一样,针对不同角色，一个场景一个场景的拍摄,最终串联成一个完整的电影作品。

这个需求,「不做」

懂得拒绝是一门艺术。

  技术人不是一个没有灵魂的代码工具。“这是需求爸爸提的,我没法拒绝”,“这是产品爸爸喊做的,不管我的事”。当出现问题的时候,我们经常听到技术同学这样说。

  不合理的需求,对用户不友好的需求,低收益,高投入的需求,要敢于拒绝。当然,拒绝也是一门艺术,这就是与人沟通的艺术。如果经过深思熟虑,你能够给出比较合理的解释或者提出更有建设性的方案,我想这样才会更加容易让人接受。

闭环

闭环这个词,真是互联网领域的万金油。但是,笔者这里特指产品需求逻辑的闭环。

  笔者曾经待过一个互联网教育创业公司。因为参与人很多都是TOB行业经验的人。大家都是知道,TOB公司的产品卖出去很多时候是线下的操作。比如,微软公司,我做操作系统一流,我赢家通吃。但是,TOC就不一定了,个体用户更加注重用户体验,比如曾经的电商百团大战的竞争,后面的共享单车的竞争,消费者可以直接用脚投票的。

  我们做了一个课程官网,包括课程展示,订阅充值的官网。官网上线之后,市场同事也做了宣传,但是发现基本上没人注册,很多用户都是让我们帮忙注册。经过研究发现了原因:

• 因为集成Azure注册慢,登录页面,而且极不友好。 这导致用户放弃注册。
• 官网没有展示客服咨询电话,只有一个用户建议表单。无法实时联系客服。

  这个案例,很典型。从市场到技术,我们做了很多工作,但是最终效果不理想。**最大的愿意就是产品不闭环。**用户想学习课程,但是登录和注册体验太差,这就已经挡住了大部分的用户。

写作套路

  前面我们讲了很多坑和避坑策略,那要如何才能写好需求文档呢？

铺垫

根据 百度百科-铺垫法。戏剧情节结构的一种手法。在戏剧的进展中，对于某些将要出现的关键性情节和起关键作用的人物，必须在事前有所准备、暗示；为情节的展开，为高潮的到来，酝酿气氛，作好准备，铺平道路。这种手法叫埋伏或伏笔。

  其实可以简单理解为背景说明。在需求文档中,增加一定的背景表述,可以增强事物间的因果联系和完整性,不显突兀。

  一般可以在你的需求前增加一个背景交代，

  这样的好处是,其一,让之前没有参与的人有个背景认识;其二,为自己后续的观点(或者设计思路)提供可信依据,至少不知自己拍脑袋想出来的。

下定义

  对于不同的业务,有时候会有一些专有名词,或者是你自己了说明某个事物而定义的名词。如果不做一些定义的解释,很难理解。比如,在设计IM聊天时候,可能会有一些定义,可以给出定义。

逻辑清晰

  需求文档,不是日记,切记流水账。排版工整,重难点突出。逻辑清晰,富有层次感。

  利用图表配合文字,有条不紊的表达出合理地逻辑。这样大家阅读起来,一目了然。

说人话

针对不同的人群一定要设计不同的话术

  这里的人是指不同的受众。考虑到需求文档面向的对象较多,有技术,业务,测试等,需要抛弃过于专业的技术语言，比如不要出现技术设计的细节,尽量要用自然语言表达。

  说句题外话,其实严格意义上,需求文档可能是要写两份,一类是给技术同学看的,一类是给非技术同学看的。对于前者,你当然可以用类似抽象的uml图或者直接给出伪代码来说明。

视角

子非鱼,安知鱼之乐

  你以为的就是你以为的吗?很多时候,需求的来源并不单一,比如公司要做一个工单系统,这个工单系统的使用者几乎涵盖了公司的各个部门。按照"用户第一"的要求,我们需要考虑到不同业务方的诉求和用户习惯。

  我们在做需求的时候,就要提前想到。否则,后面的设计一定会违背使用者的意图。前面,讲过的换位思考,或者多角色思考该排上用场了。

  在文档中,如何体现呢？通常,可以按照不通视角来描述。这就是类似程序的switch…case…

  切记站在上帝视角看待问题。

版本延续性

  需求文档很少一次性就让各方满意的,或多或少都会有补充和调整。比较好的习惯是使用修订版本来记录。

  修订历史是一个版本的可追溯源，对需求变更历程有一个清晰的认识。

  新建默认为相应模块的首次使用，对于文档的修改以及增加的地方可加入超链接，同时在增加与修改的具体地方进行颜色标示或者其他标志来进行区分，方便其他人员进行查询。

结语

  写好一个需求文档,让人觉得很专业有很多东西需要学习。这里笔者只根据个人多年的工作经验,抛砖引玉,欢迎大家怕批评和斧正。