程序员怎样写好文档？

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

然而很多项目经理害怕写文档，似乎这是一个很麻烦、 很困难的工作。其实会不会写文档，只是一种外在的表现，通过一个人写文档的情况，可以看出他对工作的理解程度，发现潜在的问题和风险。一个合格的项目经理，不但不会怕写文档， 而且会觉得这是一件简单、很自然的情，就像一个人吃饭、喝水一样，何难之有？

1.编写文档的常见问题

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

该 有的文档没有

什么叫该有的文档？我想有两点含义：一是合同、招标 文件规定必须提交的文档；二是项目本身确实需要的文档。如果仅仅是前者没有，我一般不会怪项目经理，因为事后可以补上。但如果是第二种情况，那就不只是文档本身的问题了。试想 ，如果项目执行了一半，还没有项目计划，显然就无法就事论事只谈论计划了，这反映了项目经理对整个项目的管理具有随意性，盲目性；如果没有设计文档就完成了大部分编码工作，那 么代码的质量就得打上一个大大的问号了。

项目需要的文档没有，要么是项目经理的疏忽，要么是 写不出来，这本身也是很危险的信号。如果项目经理连必需的文档都可以疏忽，说明他的工作完全没有系统性，那他对项目的管理工作怎么值得信任呢？如果是写不出来，这说明项目经理 没有想好怎么做，同样也是一件很危险的事情。

丢 三落四，内容不完整

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

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

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

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

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

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

教你自学编程从哪开始？ 

2.怎样写好文档

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

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

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

体现了知行合一

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

沟通有口头和书面两种方式，也就是说和写。想、说、 写、做四者统一，才完整体现了项目中的知行合一。说你所想的，写你所想的，否则就是言不由衷、表里不一；然后做你所说的，做你所写的，这叫说到做到、一诺千金。

图 想说写做的统一

由此可见，写你所想的，是知行合一的重要体现。

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

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

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

不要拘泥于形式

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

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

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

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

文 档结构要具逻辑性

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

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

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

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

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

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

注 意排版

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

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