无痛需求文档 Part.2

Part.2

这个系列的文章只谈需求文档，不是技术说明书。总是有人会把这两者弄混，我不知道标准的术语是怎样的，但是当我使用这些术语的时候我是这么理解的：

需求文档是用来从用户的角度来描述产品是如何运作的，它不关心你是如何实现的，在意的只是产品的特性。它指定的是程序内的各种功能和界面。

技术文档是用来描述程序的内在实现，讲的都是数据结构、数据库模型、编程语言和工具的选择和算法等。

当你全面地设计一个产品的时候，最重要事情就是弄好用户体验。界面都显示什么内容，内容如何运作，它们的作用是什么。之后你关心的是怎么从一个界面跳转到另外一个界面。当你还没决定产品做成什么样子的时候根本没必要讨论要使用什么编程语言。在这一系列文章里我只讨论需求文档。

我写了一个简短的需求文档样例来让你看看一个好的需求文档应该是什么样子的，在我们继续说下去之前，你先去看看这篇文档：链接。

你看了没？

切，你才没看，现在去看：链接，然后再回来，之后我们可以继续谈谈一份好的需求文档里应该有的和不应该有的东西。我等你，谢谢

（耐心等待中...（作者好烦…））

嗯，很好。你回来了。

下面就是一些我会放在每篇文档里的东西。

一份免责声明。纯属自我防御，如果里面里面有段话写着：“这篇文档没有完成”，别人就不会跑到你办公室然后把你头咬掉（…）。随着时间流逝，当你的文档要完成的时候，你就可以把这段话改成：“以我的能力来讲，这篇文档是完成了，但是如果我忘了什么的话，请告诉我~”，同时也提醒我，每一篇需求文档都需要：

一个且只有一个作者。一些公司认为需求文档应该由一个团队来编写。如果你试过团队写作的话，你就会知道没有比这更糟糕的折磨了。你的需求文档应该只是归属由一个人编写。如果你有一个大项目，那么就把这个项目拆分成几个部分，然后每个部分由一个人单独编写。有些公司可能认为把一个人的名字写在文档上面太自我主义和不够团队合作。无稽之谈（作者继续激动）！人们应该拥有和负责他们编写的文档。如果文档里有了什么错误的话，文档里要有一个名字来负责修复文档里的错误。

使用场景。当你设计一个产品的时候，你需要在脑中有一些用户会如何使用你的产品的场景。否则你会设计出一个不适合现实世界使用的产品。从你产品的用户挑选，想象一个虚构的但是却很典型的用户以很典型的方式使用你的产品。这就是使用场景所要包含的内容。你的场景越生动逼真，你为你真实或者想象中的用户设计产品的工作就会完成的越好，这也是为什么我会在情景中加入很多虚构的细节。

非目标需求。当你和团队一起构建一个产品的时候，每个人都有他们心爱的特性，没了这特性他就活不了（…）。如果把这些特性都实现的话，会花费无限的时间和太多的钱。你必须开始挑选特性，最好的办法就是在文档中有一个“非目标需求”的部分，也就是那些我们不会做的事情。非目标需求可能是一个不要的特性，或者是一些更普遍的准则（比如“这个版本的性能不重要，只要能运行就行，慢点没关系，在下个版本再进行优化”）。这些非目标需求可能会引起一些争论，但是越早地理清这些问题越好。

总览。就像是你文档内容的总纲，它可以是一个简单的工作流或者是总体结构的讨论。大家都会阅读总览来对你的产品有个宏观感觉，之后那些细节才会更有说服力。

细节，细节，还是细节。终于来到细节这一步了。大部分人会跳过这部分，直到他们需要知道特定的细节。在需求文档里，细节是最重要的部分。你会发现在需求样例中，对于细节发狂的追求让我列出了登录界面的各种错误情况。如果邮箱不合法怎么办？如果密码是错误的怎么办？所有的这些情况都对应着真实的代码应该怎么写，更重要的事，这些情况都是一些人一定要做的决定。总有人要决定对于丢失的密码应该是怎样的策略。如果你不决定，那么就没办法写代码。需求文档需要列出这些你做出的决定。

未确定问题。在第一版的需求中留下一些未确定的问题是可以接受。在我写第一版初稿的时候，我总是会有一些不能确定的问题，不过我会标记出他们（使用一种特殊的格式，这样可以方便我搜索），之后在合适的情况下讨论下可能的选择。随着程序员们开始工作，所有的这些问题都要被逐一解决（你可以觉得让程序员先开始做一些简单的内容，然后你之后再解决这些未确定的问题是可以的。坏主意。因为在程序实现你的设计的时候，总会有更多的问题出现。到时候你解决新的问题的时间还不够，又怎么能解决之前的老问题？除此之外，你解决重大问题的方式很有可能会对实现功能的方式产生很大的影响）。

注释。当你在写一篇需求文档的时候，记住你有各种各样的观众：程序员，测试，UI等等。在你写文档时你可能会想到只对于其中某一类人有用的信息。比如说，对于程序员有用的描述技术实现的信息我会写成“程序员注释”，UI和测试都不会看这些内容，只有程序员会看。我的需求文档里经常包含各种“测试注释”，“UI注释”，“程序员注释”等等。

需求文档要活着。一些开发团队有一种“瀑布流”心态：我们把程序都设计好，写份文档，打印出来，甩程序员脸上，然后回家。对于这种情况，我只想说“呵呵呵呵呵呵呵呵呵！”。也就是为什么需求文档名声这么差，很多人跟我说过“需求文档根本就没用，因为压根就没人按上面的来，需求总是不及时更新并且永远不会反映到产品上”。不好意思，可能你们的需求是不及时更新并且反映到产品上。但是哥的需求文档是经常更新的好么（…）。在产品开发的过程中或者有新的决定的时候，我会持续的更新需求文档。需求文档总是反映出我们对于这个产品应该如何运作的理解的集合。只有在所有的代码都写完的时候，我们的需求文档才会被冻结。为了让别人更轻松点，我不会每天都重复发布文档，我会在服务器上放上一份最新的，这样大家就可以照着这个做东西。在一些里程碑的时候，我会把有修订标记的需求文档打印出来给他们看，这样大家就可以只看有修订的地方，而不用把整个文档再看一遍了。