无痛需求文档 Part.3

（其实Part.3是原文章的Part.4，但是原文章的Part.3主要是讲产品经理的历史和如何雇佣一个产品经理，意思不大，有兴趣的可以自行观看）

OK，我们已经谈过为什么我们需要一份需求文档，一份需求文档里有什么和谁来写需求文档。在系列的最后一部分我会分享一些对于写好文档的建议。

我们从写需求文档的团队里挺大的抱怨就是“没人看需求文档”，当没人看文档的时候，那些写文档的人就会变得愤世嫉俗。在你又大又官僚的公司里，每个人都会花费几个月来写无聊的文档。一旦写好了就被放在架子上面再也不拿下来，产品从头开始也不管文档里是如何要求的，因为根本没人看文档，文档太无聊了。写文档的过程可能会是个很好的过程，因为它至少强迫每个人都仔细想想所有的问题。不过需求文档完成后却被放在柜子上这个事实让人觉得所有的工作都是无用的。

而且，如果你的文档没被读过，那么在产品提交之后可能会有很多争论。有人会说“等会！你之前跟我说的那个特性哪去了？”，程序员会说需求里也没写啊，然后仔细看看才发现，然后程序员很不乐意的加上这个特性，也让他更讨厌需求文档。或者是经理来说“你这个地方弄个不够明显啊？”，程序员就说“靠，当初文档你不是看过了说没问题的么，你现在来找我？”，事实当然是那个经理根本就没看过需求文档。

所以呀，需求文档是很棒的，不过如果没人读的话也就失去了意义。作为一个写需求文档的人，你必须“骗”人去读你写的东西，而且要尽量别让别人一看到你的文档就想睡觉。

骗人去读你写的东西一般是都需要好文笔。但是如果我跟你说当个好作者然后不管你了对你来说也不太公平，以下就是一些让你的文档被阅读的基本法则，你一定要遵守！

** 法则 1：要有趣 **

对的，骗人看你文档的第一条法则就是让别人的阅读体验更有趣，别跟我说你生下来就没啥意思，我不信（我信...）。每个人一直都会有一些有趣的想法，他们只是自我删除了那些想法，因为他们觉得这样“不专业”。不过有时候你就是要打破这些规则。如果你还是觉得有趣就是不专业的话，那么不好意思，你就是没有幽默感（别否认，没幽默感的总是否认，你骗不了我！），如果你是在一个看了你有趣又欢快的文档就不尊重你的公司的话，那你最好换家公司，因为人生苦短，没必要把你白天的大把好时光画在这种无聊的公司。

** 法则 2：写文档就像是写给大脑执行的代码 **

以下就是为什么我觉得程序员们写不好优秀的需求文档。

当你写代码的时候，你主要的听众是编译器。对，我知道人也得看代码，不过这对他们很难就是了。对于大部分程序员来讲，能够写出让编译器能够识别并且正确的表述的代码已经很难了，考虑人可读的代码就是奢侈品了。

void print_count( FILE* a, char * b, int c ){ fprintf(a, "there are %d %s\n", c, b);}main(){ int n; n = 10; print_count(stdout, "employees", n) /* codedeliberately obfuscated */ }

printf("there are 10 employees\n");

上面这两段代码的输出是一样的。这也就是为什么你需要照看一些把东西写成这样的程序员：

Assume a function AddressOf(x) which is defined as the mapping from a user x, to the RFC-822 compliant email address of that user, an ANSI string. Let us assume user A and user B, where A wants to send an email to user B. So user A initiates a new message using any (but not all) of the techniques defined elsewhere, and types AddressOf(B) in the To: editbox.

这个也可以被写成：

Miss Piggy wants to go to lunch, so she starts a new email and types Kermit's address in the "To:" box. Technical note: the address must be a standard Internet address (RFC-822 compliant.)

理论上讲，这两个其实说的都是同样的事情，不过前一个很不好懂，除非你很仔细的解码它，相比之下，第二个就很容易理解，开发者经常试着把文档写成高密度的大学论文，他们认为一个“正确”的文档应该是“技术”上正确的。

问题是当你写一篇需求文档的时候，相比于正确性，更重要的是要可理解，也就是说用编程的术语来讲，你要让你阅读者的大脑能够编译它。人脑和电脑一个最大的区别就是，当你定义之后要使用的变量的时候，电脑会耐心的等着。但是人不会知道你在说什么，除非你先提前告诉他。人都不想解码什么东西，只是想按顺序读下去就能理解。对人类来说，你要先提供总体框架，然后再填入细节。电脑程序就是从头到尾满是细节的执行，电脑不会在意你的变量名是否有意义。但是如果你能通过讲个故事让人脑中产生画面的话，那么他就能更好的理解你说的东西，即使只是故事中的一部分，因为我们的大脑已经进化到能够理解故事。

如果你拿出一个正在游戏中的棋盘给有经验的棋手看，即使只有一两秒的话，他们也会立刻记住每个棋子的位置。但是如果你移动几个棋子到它们不可能去的地方的话，对他们来说就会非常难记住。这和电脑有很大的不同，无论你的棋子是在合理的地方还是不合理的地方对电脑来说都是一样。我们的大脑不像电脑那样是随机读取的，所以注定有些常见的事情比其他的要更好理解。

所以在你写需求文档的时候，试着想象看你文档的人，你要让他在每一步理解的东西是什么。一句一句地看你写的东西，然后问你自己：在看的人是否能在所知的上下文之下，深入理解你所说的内容。所以当你的目标读者不懂RFC-822这个词的意思时候，你告诉他这是什么意思，或者至少在技术注释中写出它的意思，这样至少在你读者在第一次看到这个词的时候不会放弃读你的需求文档。

** 法则 3：写的越简单越好 **

不要因为觉得不专业就在简单的句子里写一些不自然和正式的文字，用你觉得最简单的语言。

把内容分解成短句。如果你不能把一句话写清楚，那么就把它分成两三个短句。避免文字墙（也就是整页都是文字），因为看到文字墙别人就会因为害怕而不读需求文档了。最后一次你看到流行杂志满页都是文字是什么时候？杂志会使用很大的字体在文字的旁边加入引用，这样就不会有满页都是文字的情况了。使用列表，图片，表格和空行会让文字看起来更轻松。

没有什么比大把的屏幕截图能更好的提高一份需求文档了。古人云：一图抵千字。把你截的图放进你的文档里可以让别人更容易的理解你要表达的内容。

** 法则 4：回顾重读你的文档几次 **

好吧，我本来打算写大把的文字来解释一下，不过这条规则就是这么简单和明显。检查和重读你的文档几次好不？当你发现一个句子不是特别好理解的时候就重写一下。

因为在法则4里省了不少时间，那我就再加一条法则吧。

** 法则 5：模板有害 **

要避免被为需求文档做模板的这个想法所诱惑。可能开始的时候你会觉得“让每篇需求文档都长一样”这个事情很重要。不过其实不是，你书架上的书都一样？你想让他们都一样么？

更坏的是，如果你有模板的话，很可能发生的事情是你会把一堆可能对每个特性都很重要的内容加进去。所以在使用这个模板的时候，不过有没有相应的内容，你都往里面添加一些你本来没必要写的东西。随着这种内容的积累，你的模板会越变越大。这样的问题就是当你的模板这么大的时候，写需求就变成了一项可怕的任务，也就没人会愿意写了。谁会需要在需求文档里有参考书目或者术语表？

需求文档是你希望别人去读的东西，按这种说法来看的话，它和《纽约客》里面的文章或者大学论文（R U Sure？...）没有区别。你听说过大学老师给学生一份模板让他写论文么？你听过两篇《纽约客》的文章可以被放进一个模板么？还是放弃模板这个想法吧。

The End