从程序员到项目经理（29）：怎样写文档

在软件项目中，文档既是一项的重要成果，也是项目管 理的有力工具。经过文档，能够稳定、明确的传达信息，实现项目内的有效沟通。因此写文档对项目经理来讲，是一项必备的技能。

然而不少项目经理惧怕写文档，彷佛这是一个很麻烦、 很困难的工做。其实会不会写文档，只是一种外在的表现，经过一我的写文档的状况，能够看出他对工做的理解程度，发现潜在的问题和风险。一个合格的项目经理，不但不会怕写文档， 并且会以为这是一件简单、很天然的情，就像一我的吃饭、喝水同样，何难之有？

（本人拙做《程序员第二步 -从程序员到项目经理》即将面市，敬请关注~~ 当当网已可预订http://product.dangdang.com/23365823.html） 

1.编写文档的常见问题

每一个项目都要写很多文档，好比项目实施计划、系统需 求说明书、系统概要设计设计、系统详细设计、测试计划……在很多软件项目中，大部分文档写出来只是为了应付检查或验收，若是要对这些文档较真的话，就会发现它们存在着各类各样的问题。

该 有的文档没有

什么叫该有的文档？我想有两点含义：一是合同、招标 文件规定必须提交的文档；二是项目自己确实须要的文档。若是仅仅是前者没有，我通常不会怪项目经理，由于过后能够补上。但若是是第二种状况，那就不仅是文档自己的问题了。试想 ，若是项目执行了一半，尚未项目计划，显然就没法就事论事只谈论计划了，这反映了项目经理对整个项目的管理具备随意性，盲目性；若是没有设计文档就完成了大部分编码工做，那 么代码的质量就得打上一个大大的问号了。

项目须要的文档没有，要么是项目经理的疏忽，要么是 写不出来，这自己也是很危险的信号。若是项目经理连必需的文档均可以疏忽，说明他的工做彻底没有系统性，那他对项目的管理工做怎么值得信任呢？若是是写不出来，这说明项目经理 没有想好怎么作，一样也是一件很危险的事情。

丢 三落四，内容不完整

打开文档一看，老是有一些你想看的内容找不到，或者 对关键的内容轻描淡写，这多少会让人以为有点生气。项目计划没有工做分解，设计文档没有系统逻辑结构，项目周报没有当前进度状况，试运行报告没有系统运行的统计数据 ……出现这样的状态，说 明项目经理缺少经验，对项目没有整体的认识，更加把握不了工做的重点。

照 搬模板，徒具形式，内容空洞

这种文档还真让人有点迫不得已。乍一看，文档格式规 范、内容完整，彷佛没什么问题，但内心总以为少了一些东西，看完了什么也没记住，仿佛没看过同样。简单的说，就是没有实质性内容，缺少对问题的具体分析，一样的内容，改一下名 字，能够给其它项目用。

这样说项目经理可能会不服气：我文档有几百页，怎么 会没内容呢？好吧，咱们来清理一下，把模板自带的内容去掉、把合同和招标文件中Copy的内容去掉、把网上抄的内容去掉、把不相关的内容去掉、再把不重要内容去掉，再来看看究竟还剩下几页？这剩下的内容才是真 正有价值的东西。若是这一部份内容不多，你文档越长，就会越像懒婆娘的裹脚布，让人生厌。

看这样的文档，让人以为就像吃了苍蝇同样难受。有人 将这种文档称之为“模板僵尸”，真是既准确、又解恨。这种文档徒具形式，没有灵魂、没有精神，就像一具只有骨架、没有血肉的僵尸。

写出或者接受这种文档的项目经理也很可怕。 他有经验，可是没想法；他知道流程，但不知道变化；他能把握形式，但把握不了内在；他明白要作什么，却永远也理不清楚工做的内容；他写的内 容不少，脑中却几乎一片空白。他们写出来的文档像僵尸，作项目也像被僵尸附身同样，只能沿着固定的路径一蹦一跳的前进，哪怕前面有深渊，他也会直接跳下去，因 为他压根就看不到！

2.怎样写好文档

我见过很多工做十年以上、管过项目五年以上的同事， 对于写项目文档仍然是愁眉苦脸、痛苦不堪。难道写文档真的有这么难吗？怎样才能写出合格的项目文档呢？

最核心的一点，写你所想的

俗话说：“言为心声”，写做也是一种 “言”，一样体现了做者的心里想法。写项目文档，最重要的就是要写本身的真实想法，展现本身的思路。若是说写文档有什么诀窍的话，这就是最重要的诀窍。从哲学上来讲 ，这是知行合一的重要一环；从写文档自己来讲，只有这样才写得好、写得快。因此若是有谁说本身不会写文档，咱们首先应该想到的不是什么技巧问题，而是他真的想好了吗？

体现了知行合一

“知行合一”也就是“想”和 “作”应当保持一致。知行合一最简单的方法，就是想了就去作，由想直接到作。在软件行业我的英雄主义年代，程序员有好的想法，而后实现它，就有可能成就一段传奇，例 如UCDOS、WPS、RichWin、江民杀毒等都是那个时代的产物。由想直接到作，这对于一我的完成的 简单工做是能够的，但并不适合于由多人协做完成的复杂任务，由于团队做战还有一个关键环节——沟通。

沟通有口头和书面两种方式，也就是说和写。想、说、 写、作四者统一，才完总体现了项目中的知行合一。说你所想的，写你所想的，不然就是言不禁衷、表里不一；而后作你所说的，作你所写的，这叫说到作到、一言既出;驷马难追。

图 想说写作的统一

因而可知，写你所想的，是知行合一的重要体现。

写所想的才能写得好、 写得快

为何有些人写文档写得很慢 、以为很痛苦呢？最根本的缘由就是由于他没有想法，或者说没想好，肚子里没货天然拿不出来。比 如说，若是你不熟悉Java技术，让你 来写一个Java系统的设计文档，你自 然不知从哪里下手，纵使你有莫言同样的文采和想象力，也没有办法完成。

写你所想的，其实只是把想法 誊到纸上而已，就像把杯子里的水倒出来同样。有思路的话，固然能写得快、写得好。若是没有想法 ，千万不要不懂装懂，到网上处处复制一些看上去相关的内容来填补，由于这会误导别人，虽然掩盖了本身的无知，但也掩盖项目隐藏的问题和风险。因此对于没有想清楚的地方，最好的 处理方法就是直接写上“没想好”三个大字，等想好了再补上。记住：说假话的人最辛苦，由于他老是要琢磨该怎样编故事，怎样自圆其说。讲真话的人最轻松，写文档就是要 写本身的真心话。

不要拘泥于形式

有些人说：“我有想法，就是写不出来。” 这种状况多半是因为写做者拘泥于文档的形式，不知该如何下笔。这样的话，有一个简单的方法：先把你的想法说出来，用手机把声音给录下来，而后对照录音来整理文档。也就是说，我 们要像说话同样写文档，说话是很天然的事情，写文档也是很天然的事情。若是你没办法说清楚，那估计神仙也法办法了——除非有谁懂得读心术。

文档最重要的是内容和思想，让读者能读懂你的思路， 而不是构思有多精巧，语言有多优美。若是老是在琢磨先写什么，再写什么，用什么词，怎么能快得了呢？

不拘泥于形式的另外一含义是不要有过多形式化的内容。 有时一篇30页的文档，项目背景、建 设目标、参考资料之类就占掉15页， 而且在每一篇中都千篇一概。这些东西不是彻底没用，但过多就会影响对文档重点的把握，尽可砍掉或简化。

另外不要凑篇幅。项目文档是用来指导项目实施的，因 此把问题写清楚就能够了，多写无益。有些人写文档时，喜欢问要写多少页，其实这根本不该该成为一个问题，若是把想说的都说清楚了，你管它有多少页呢 ？

文 档结构要具逻辑性

在第三章中，曾经提到PMBok项目管理理论遵循结构化的思想，即自顶向下、逐层分解。 这一规律一样能够用来指导文档的编写，项目文档在结构上一样应该是“结构化”的，自顶向下、逐层分解，造成金字塔形的结构。

还记得在学校里老师教咱们怎样写做文了吗？要按 “总分”或“总分总”的结构来写，这其实也是结构化方法的体现。结构化方法之因此放之四海而皆准，是由于它符合人对事物的认识规律。

设想咱们要研读一本书，通常咱们首先会看书名、做者 ，再看目录、前言或简介，对全书全造成一个整体的印象，这是“总”的过程。而后咱们会逐章逐节的阅读，一步一步消化全书的内容，这是一个“分”的过程。部 分读者在读完之后，可能还会对全书的内容进行再次总结回顾，以进一步加深理解，这又是一个“总”的过程。经过这样一个“总分总”的过程，咱们造成了对事物 的深入理解。

因此一本书按照金字塔结构来组织文档，其实就是为了 迎合读者，下降他们理解的难度，让他们只须要更少的时间就能够对整个文档的精要有一个完整准确的理解。做者写得轻松、读者读得开心，真是皆大欢喜。

结构化方法不但适用于文档的总体结构，一样适用于局 部结构，例如文档的某一节。只要事物具备必定的复杂度，咱们均可以用这种方式将其讲得更加透彻。

采用结构化方法来编写文档还有一个好处，就是能够检 验思惟的严谨性。结构化方法的一个重要工做就是对事物进行分解，而分解的过程实际上是一个再次深刻思考的过程，例如分解的标准是什么，上层结构是否完整的包含了下层结构等，从而 发现被遗漏的问题，并进行完善。

注 意排版

文档排版是许多人容易忽视的问题。一分内容上乘的文 档，若是用工整悦目的排版来展示，那就是锦上添花了，反之就有损文档做者的形象。这就比如一我的心灵美当然重要，但若是穿着邋遢，面目可憎，也不大可能会受到别人的欢迎。

排版并不是难事，只须要投入很小工做量，就能够为文档 得到必定的加分，这就是排版的价值。事实上，排版仍是对读者尊重的表现。做者多花一点点精力，就可让读者拥有更好的阅读心情，更快的阅读速度，实在是一种设身处地为他人着想 的美德。