软件需求文档可以这样写 ---- “香皮匠式”需求文档

发布者： Wenzhe

不同的team对于同一个需求的理解是不完全一样的，甚至有可能完全不一样。由于知识背景的差异、工作重心的差异，看问题的角度也不一样，见解自然也就容易产生分歧。比如：

1.产品人员注重产品的功能、外观、易用性、可靠性，以及能为客户解决哪些实际问题，带来多少好处。特别是站在用户的角度考虑问题，想客户之所想，提出合理的需求让开发人员去实现。成就感来自于用户对产品的认可和赞扬，让客户Happy！

2.算法人员注重产品逻辑功能的底层实现，兴趣点在于建立良好的数学模型，用高效率的算法解决问题。特别是从算法效率的角度考虑问题，成就感来自于数学之美，巧妙精美地解决各种技术难题，世上无难事，只要有数学！相当Happy！

3.应用软件人员注重软件本身的架构设计，兴趣点在于软件产品的可读性、可复用性、可扩展性、可维护性等等。特别是从软件设计原则/模式的角度考虑问题，成就感来自于软件之美，能够轻易拥抱不断变化的需求，能够让傻子也能读懂，甚至当成小说那样的喜欢读，让代码的维护不再枯燥，而是如同打游戏一般的Happy！

4.测试人员注重需求的测试点，同样的需求他们会考虑到各种case，以及边缘性的case。兴趣点在于寻找产品中的bug，像玩扫雷游戏一样有趣。有时候发现问题比解决问题更重要，发现bug其实也是一件很爽的事！

因此，写需求文档的时候，每个team都从自己的角度来写，却往往很少考虑其他team的人是否能够准确理解你的需求，或者说，你的需求是否能让其他team的人理解。这其实是一个跨team之间的交流沟通的问题，也可以说是一个工作流程的问题。

其实我认为，你的需求不能让其他人正确的理解，甚至是误解，你至少应该负50%的责任！因为那个不清晰的、可读性差的需求浪费了别人宝贵的时间去尝试理解，去交流，甚至浪费别人辛苦的劳动去实现他们错误的理解。同时也是在浪费自己的时间，因为当每个team找你问清楚的时候，你都要做重复的解释。可见需求文档在项目开发中的重要性是不可忽略的！

中国有句俗话“三个臭皮匠，赛过诸葛亮”，从各个角度来集思广益，往往可以超乎想象！基于这个思路，本文提出了一种写需求文档的方法，本来想干脆就命名为“臭皮匠式”需求文档，但觉得有辱于我们这些劳动人民。而且也不符合实情，因为劳动才是最美最香的，劳动人民才是最香的人，因此取名为：“香皮匠式”需求文档，听起来都有胃口了！（看来今晚可以多吃几碗）也期待这种方法可以被广泛应用，像鲜花一样，芳香百里！

当有一个需求的时候，一般会提出一个ticket来记录（一般是在网页上，如JIRA等工具，用于跟踪需求，以及开发，测试，讨论等）。“香皮匠式”需求文档，就是在ticket上，每个team都有一个自己comments的空间，而且不能修改其他team的空间。然后，每个team都根据自己对需求的理解，从自己的角度写到ticket上的相应位置去：这包括对于这个需求这个team的理解，以及计划完成哪些任务，当任务大的时候需要分解为小任务。这样一来，每个人都可以从ticket上看到各个team所关注的重点、理解、以及计划的任务。如果发现理解中有些误差，可以及时发现问题，及时讨论，调整计划，补充说明，相互提醒。有必要的时候，几个team的人可以坐在一起开个crossteam meeting讨论下，尽早地避免因理解不同而产生不必要的误会，尽早地避免“返工”所造成的时间损失。经过参考其他team的理解，很多时候，都会发现自己原来的理解有些片面，那就去ticket上面去补充，进一步去完善自己team的任务计划。从反馈理论将，需求文档的编写是一个负反馈的系统，需要每个team都参与编写，根据其他team的输入，通过讨论与自省，不断减小理解的误差，最终形成一份稳定的需求文档。

这是很有好处的。一般来说，由于工作性质的差异，测试人员考虑问题往往比开发人员要周到一些。在编码之前，应用软件开发人员就可以根据ticket上测试人员写到测试用例计划细节，清楚知道什么才是期望的结果，清楚知道什么是bug，编码中需要关注哪些边界问题，考虑问题就会更加全面一些（比如改到这一功能，要确保那一功能不被破坏），而且更好地去编写单元测试（unittest），更方便地实施测试驱动开发，有的放矢。

产品人员所掌握的业务知识一般也比开发人员要好一些，软件开发人员就可以根据ticket上产品人员对需求的理解来弄清楚更多的业务领域概念，从而可以更准确地设计软件的domain模型，更加恰当地运用领域驱动设计软件，写出更优秀的代码；而且也可以清楚知道哪些是用户最care的，从而可以更好的分清楚任务的优先级，有助于开发计划的制定。

同属研发人员，算法研究人员与应用软件开发人员侧重点却是有所不同的，一般来说，应用软件会去调用算法team提供的底层服务来完成某项任务，这个服务的接口就相当重要！通过各自在ticket上的任务计划和服务接口约定，两个研发团队就可以分头行事，并行研发，提高工作效率。

当一个算法team提出GUI应用软件需求时，他们会按照他们的想法来描述需求。GUI应用软件开发人员不一定能看懂这些深奥的算法语言，当然也无需完全100%理解这些术语，对他们来说，更重要的是需要弄清楚GUI应该做什么，怎么去调用算法team的底层服务接口就行，如果不明白需求要做什么，得先跟reporter交流，直到弄明白为止。当然reporter在写需求时得必须尽量能让其他team的人明白，少用别人看不懂的术语和缩写。然后GUI应用软件team将要完成的工作任务一条条细化，必要时建立subtask，并且写入到需求文档的相应位置中，这就是在告诉大家，这就是他们的理解，这就是他们要做的所有事情，你有异议的话就尽快给他们反馈。

算法人员可以根据GUI应用软件team所描述的需求理解，去了解是否符合他们的要求。

而产品人员也可以尽早地通过GUI team的需求理解和估算来给市场方面提供建议，尽早反馈和清楚人员的工作任务，而不是等到软件做出来之后才发现原本的需求不符合客户的真正需求，那时候再修改，浪费的资源可就多了。

测试人员应该根据GUI team的需求理解和任务分解，写下他们的测试点，尽早反馈和发现问题（有些bug是可以在代码编写之前发现的，比如GUI分解的任务考虑不够周全，需要再分解些任务去解决）。这样可以尽量尽早地减小理解误差，避免造成以后做出的是一套，而测试的期待结果确是另一套，到那时候再fire出无数的bug，那就杯具了。

一份完善的需求文档的形成，需要经过以下3个阶段：

1.雏形阶段：每个team根据自己的理解，任务分解，估算，写入到ticket上属于自己team的空间。

2.成形阶段：经过吸收其他team的理解，讨论，从而进一步深入自己的理解，改进和完善文档。

3.稳定阶段：当每个team之间消除了误差，都能接受其他team的意见，达成一致，并且认为自己team的任务计划已经完善时，需求文档也就定下来了。 以后就不能随随便便修改需求。倘若真的要修改，你需要有足够的理由去说服参与该ticket的所有team，需要大家一致同意才行。保持需求文档的稳定性，是很重要的，如果今天不爽就改需求，明天特爽也改需求，那么需求文档就是废纸一张了。

“香皮匠式”需求文档的格式是必须包括以下内容：

Ticket ID: xxx (由reporter创建)

Title: xxx (由reporter提供)

Description: xxx (由reporter提供)

Priority: xxx (有项目管理者设定)

Assignee: Wenzhe Liu (由哪个team或者哪个人来完成任务最合适，比如我，^_^)

Reporter: xxx

Product Team Input Area:

Requirement understanding: xxx

What is needed for the requirement:xxx

Related tickets:xxx, xxx (类似的需求，相关背景，父需求，子需求)

Algorithm Team Input Area:

Requirement understanding: xxx

What to do for the requirement: xxx

Sub-Tasktickets: xxx, xxx (分解为一个个的小任务)

Estimate:xxx (估算完成得花多少时间)

Application Software Team Input Area:

Requirement understanding: xxx

What to do for the requirement: xxx

Sub-Tasktickets: xxx, xxx (分解为一个个的小任务)

Estimate:xxx (估算完成得花多少时间)

QA Team Input Area:

Requirement understanding: xxx

What to test for the requirement:xxx

Bug tickets: xxx, xxx (与此ticket相关的bug通通link过来)

在编码之前，有一份完善的、多角度的需求文档，可以尽早发现问题，降低风险，有的放矢，做客户真正急切需要的事，而不是白干、蛮干。而且有助于以后做需求管理，分析总结，需求跟踪，并且有助于新同事快速理解项目，有助于所有团队整体效率的提高，真正做到1+ 1 > 2。