关于文档编写

写文档的困惑

写文档不像写代码，它没有明确的好与坏，更没有明显的正确与不正确。也正因为此，对于写惯了代码的程序员来说，写文档是无比痛苦的，完全找不着北。

写短了，人家说没写清楚，太不详细；写得长了，人家说太琐碎，那么长，哪有精力看。

领导说，“这个问题简单，两三页随便描述一下就行了。”你若真是只写个两三页，百分之百挨批。

又要言简意赅，又要表述详尽。这比写代码要费劲多了。

我们写代码时，讲什么重构呀重构，有几个人写完代码重构的？没几个吧。有哪一个写完程序重构个十来回的？亘古少有吧。而写文档，随便一个文档，被重构个十来回、几十回，甚至推倒重来个几回都很正常。

写代码与写文档，完全是两个境界。要不怎么说，写代码的工资，不如写文档的；写文档的工资不如写PPT的。PPT相对于文档更加精炼，所以写起来更困难。

看文档的困惑

商务经理写的立项说明，研发经理看不明白；项目经理写的需求分析，开发人员看不明白，包括我自己写的文档也有别人看不懂的时候，呵呵。

当然了，我这么说，会有人很不服气，“哪里不明白？你说哪里不明白？哪不明白你问我，我给你讲。”

尤其常见的是，当新员工拿到开发资料后，看不懂，只好问老员工，老员工不耐烦，“文档上不是写的很清楚吗？找不着？这里，这里，不是吗？……看不懂？你自己看不懂怨谁？”新员工不吭声了，郁闷到一定程度就悄悄辞职了，剩下牛逼哄哄的老员工发牢骚。

我也坦诚，大多数项目文档，我都没有从开头看到结尾过，哪怕两三页的文档，都是跳读。其实不仅是项目文档，除了小 说，几乎所有的书籍、资料我都是跳读，浏览一下大概意思就完事儿了，具体到某个问题时，再着重阅读相关章节。问题在于，重点问题往往没有重点表达。

一般阅读文档都会通过文档结构图来查阅，那个文档结构图其实就是文档的骨架。一个完整的文档自然是从头到脚都有的，但我们并不会从头看到脚。就像我们看一个人一样，如果对方胳膊腿少一样我们都会感到吃惊，但我们面对对方时，却不会从头到看到脚，如果真这样，实在太不礼貌了。我们只需关注重点。

文档模板的编写

单纯依靠作者的文字能力、创作能力写出好的文档是不靠谱的，毕竟大家不是专业写手。基本思路还是“套模板”，软件工程有国标的文档模板，也有ISO的文档模板，也有CMMI的文档模板，可是任何一个模板拿过来，都不好往上套，实在让人郁闷。究其原因，那些模板只是一个壳，没有任何编写指导，编不出来东西。

我想，好的文档模板应该遵循如下原则：

可选、可删、可填、可编；

能够让作者打勾选择的内容项，尽量打勾选择，例如文档保密级别，可以提供三项供选择“□普通 □保密 □机密”而不是让作者去填写，他有可能不知道该填什么；

其次是“可删”，即内容可以删减，模板中尽可能提供一些常用的文档段落，例如，文档的目标读者，可以在模板中列举出尽可能多的目标读者，如“目标读者包括：总经理，技术总监，项目经理，客户经理，需求分析人员，系统架构师，项目建设方负责人”；作者在编写文档时根据需要删除多余的，如果让作者增加内容，他可能不太容易想的周全。

再其次是“可填”，前文说过，文档往往重点内容没有重点表达，甚至会遗漏关键问题的描述，原因也不是作者不想去写清楚，往往是事情多，一时思虑不周造成的。那么在模板中尽可能把需要描述的内容列举出来，例如，项目概述部分，涉及项目目标、功能范围、工期约束、承建单位、项目规模、验收方式等等，在模板中逐个列举，供作者填写，这样就不会遗漏内容项。

最后，就是“可编”了，毕竟文档中还有很多内容需要作者根据具体的项目情况需要编写，这个工作有一定的创造性，也最让人感觉困难，建议编写时参考以往的文档，比葫芦画瓢是最基础技法。

大家可能会想，有这样的模板真是太好了，可这样的文档模板容易做出来吗？的确不太容易，仅靠项目经理来组织编写文档模板是完全不够的，如果公司有项目管理部门，或项目管理委员会（PMO）出面来处理这个事情，会好一些。

文档内容的编写

文档编写比较麻烦，我在这里说一下我的编写心得。

在文档的编写过程中，我用的最多的软件并不是Word，而MindManager与OneNote，Word仅用于最后的文档编排与修订。

MindManager顾名思义是思维管理的工具，可以用它画思维导图、结构图等，还可以进行头脑风暴。当我要开始编写某个东西时，我一般会用MindManager的头脑风暴功能，把自己能想到的、相关的所有内容，都敲出来，然后把这些内容进行归纳、增删、编排，很快一个像八爪鱼一样的思维导图就出来了，这其实就是文档的“骨架”雏形。这个图我会经过若干次调整，直到觉得比较完美了，才开始编写文档。

当然了，在修订思维导图的过程中，肯定要陆续的收集相关资料，文字、图片、参考文档等等。这个时候就用到了OneNote这个软件，它是Office2010中的套件之一，用于收集资料非常方便。它支持图文混排，可以随时摘录，会自动存档，带录音功能，可以无限制的划分标签。如果说MindManager在搭建文档的“骨架”，它就是在组织文档的“血肉”。

等一切都妥当了，再把相关文档模板拿来，把整理好的内容往里面填充，这样，一个格式完整、思路清晰、内容充实的文档就出炉了。最后就是排版，这是Word专长。

后记

我发现很多同事用的文档编辑软件都不一样，有用Word2010的，有用Word2003的，还有用WPS的，这不能说不行，但它在文档交流过程中会造成一些不方便。为什么我们软件开发的工具会很容易统一，但办公软件却难以统一起来呢？究期原因，我想，还是在大家心里，“研发管理”的地位还远低于“研发”本身。