再谈文档必不可少

项目文档必不可少，必不可少，再小的项目，别人再和你吹嘘项目多么简单，领导再告诉你时间多么紧张，客户再不上线就要损失几十万，统统都不是你的问题，唯独不写文档是你的责任！
我在《人月神话》的解读中已经深入的理解了文档的必要性，很多时候人只是还不够强大，经常败在时间上，败在压力上。

需求文档

首先，需求文档。需求文档是我们把客户心里想的东西写出来给客户看，或者有时候是客户提供的，所以需求文档往往是最不能体现项目功能的。在这个文档中，我们一定要适应客户的口吻，换句话说要用客户看得懂的话，而且一定不要往细里写，因为还不是时候。这个文档要确定的是项目的目的，这个目标一定要简短，如果一个项目的目标太多，可以写多份需求文档来分别说明。
《简约之美》这本书中，作者认为项目的目的归根结底只有一个，那就是帮助人。由此我觉得需求可以这么写，首先明确项目给谁用，再明确帮他实现了什么价值，所有的项目都可以这么写。

系统设计文档

往后是，系统设计。这是专业的程序人员或者产品经理的工作结果，应该要细化，但不可避免的会出现很多口水话，导致客户看不懂甚至不想看。但没有关系，系统设计的编写应该占程序员工作的50%是为合理的。改文档总是比改项目来的快，而且安全。之所以安全是因为文档的思路是连贯的，更容易观察到冲突和矛盾，书写的过程同时也是思考的过程，打字的时候真的能让人想通很多问题。

但是问题又来了，客户对于文档没有热情怎么办？客户语文实在是差怎么办？

实际上我们无法避免，客户的水平肯定是参差不齐的，不能要求他们所有都对互联网有较好的理解。我们能做的就是为文档编写文档。我发现这并不是多么难的事情，我需要教会客户如何写文档以及阅读文档。如果说文档是一种沟通工具的话，那么交流的双方都必须理解这种工具的内容所代表的具体含义。同时，我们对待这件事情越认真客户也越能意识到它的重要性，而不是再纠结于成本和周期而放弃文档。

那么这些为文档所编写的文档，实际上是公司 Wiki 的一部分，而且是公开的那一部分。我认为这是今后一段时间，乃至长久的一项重要工作。我希望做到的是让客户通过 config 一样的形式，就能实现良好的文档交流。

测试文档

最后是，测试文档。在某个项目之后，我意识到，我们必须让测试不再依赖于个人，特别是不再依赖于客户。如果最终测试依赖于个人而不是文档将会产生许多的不稳定因素。

• 首先，测试者的心态会发生改变，如果项目质量仅由一人评估，整个项目就很容易出现一些人性的错误。例如，主观但错误的推测（对于功能的曲解或过度解读），存在但无价值的选择（对于个人口味的青睐）。
• 其次，脱离文档的测试容易丢失主要目标（就是那个帮助人的目标），测试者不是设计者，他只关注于某个过程，对于项目整体很难把握。
• 最后，也是最可怕的，没有文档的话测试与需求容易被混为一谈。测试应当源自于需求文档，而不是源自于市场或者环境。

测试文档产生于前期准备工作阶段，主要是对于需求文档仔细研究的结果，用于指导测试流程。

如何让文档不形同虚设？

上面提到的三个工作文档，比起专业书籍中的类目要少了很多，因为我认为最重要只有这三个，其他的过于形式。文档本身作为一种工具，实质必然重于形式。曾经也有重服务、轻文档的客户案例，但我认为这是建立在沟通顺畅的基础上。那么沟通顺畅本身又是一件很主观的事情，我们看很多书写情商、影响力和沟通技巧的，都没法把这个问题讲清楚。软件行业的生产效率不能像其他制造业一样用人和时间进行计算，主要也是因为沟通成本无法降低。
如何让文档真正有效的降低沟通成本，就是让文档不形同虚设的关键。我认为有两点：

1. 技术高层必须给予支持和认同。文档往往败于时间，质量和周期本来就是矛盾，如果技术高层不认同文档沟通，那么很少有技术员能够抗住这样的压力坚持做正确的事。
2. 客户必须经过基本的筛选，宁缺毋滥。特别是对技术驱动型以及产品驱动型的客户，如果对互联网知之甚少，建议选择不合作。现在市场环境中，确实有那么些人是不了解以至于不尊重软件从业人员工作结果的。
3. 开发人员必须认同这样的开发方式。程序员的两大痛苦就是：为什么要写文档，以及，为什么没写文档。

你的文档仍然一文不值怎么办？

你没有做错什么，但你仍然失败了。客户说我不改需求不给钱，商务说文档只是参考，领导说你为什么不早点开始写代码，公司表示这一切无能为力。请继续写好文档，这些问题都不是文档造成的。如果仔细分析会发现，其他他们都来自于错误的进度估计。
请在下一个项目的文档中进行正确的开发进度安排，需求的修改也必定意味着新的文档产生。

END
如需转载，注明出处，并不需要我同意