文档的价值？

前言：
提起软件工程、ISO体系、CMM、RUP，甚至项目管理，都会给人一种强化控制的感觉：要写一堆文档，要填写一堆的报表，要经常开会评审……。
现在软件工厂、蓝领之类的观点颇有市场，一些专家鼓吹通过过程控制、文档驱动、蓝领开发来进行软件项目开发。
这种思想的基础：文档驱动、装配流水线我个人认为是错误的。先说说文档，装配线的事还得准备一段时间。

文档的价值
文档的价值真有那么大吗？我赞成写文档，但不赞成文档驱动，更反感那些将软件人员当作螺丝钉的“工程”思想。

文档可以简单的分成两类：开发文档和管理文档。

一、开发文档
开发文档的用途我认为主要是三点：沟通、质量控制和维护。

1、沟通
文档代替不了沟通。在沟通这个环节，文档的价值很小。
如果公司人员稳定、项目组内部团结、设计开发能力强、代码编写规范、项目规模不大的情况下，文档的沟通价值远远不及小组内部面对面的沟通，这种时候开发文档可以写的很少，可能最重要的是用例分析文档和原型，通过及时的小组会议和代码评审，代码就可以解决问题，所以微软说“代码即文档”有一定道理。（当然这种思想也和进度压力有关系，有些日本公司如日产公司对质量要求较高，给了很充裕的时间写文档，客户要求写，也算作开发时间，但这种客户是少数。）
如果小组内部大部分人员的开发经验不足，就不要想通过文档来指导开发，文档没有什么用途。
大部分开发文档可以通过工具导出，事后补文档也没有什么不对的，：）。

2、质量控制
开发文档的第二个用途是质量控制。
在阶段性工作完成后要进行评审，往往都是将文档做为成果物提交给客户和公司内部评审人员进行评审，很多时候效果不好，走走过场，对项目的下阶段工作没有意义。
项目成果可以分为两类：业务成果和技术成果。
业务成果的评审主要是客户来进行评估，一般给业务流程图、原型就可以了，公司内部人员如果不是该业务领域的专家就没有必要参加，听不懂客户的业务在那耗着还不如回去干自己的事。
技术成果的评审也要是相关领域技术能力很强的人员参加，最好平时就对技术设计思路和方法有充分的沟通，否则到评审前来理解设计思路是很难的，评审的时候对。
从这也可以看出，项目组的内部和外部沟通是非常关键的，否则最后的评审就是看看文档符不符合排版标准，有没有错别字，质量控制也失去了意义。

3、维护
开发文档用途最大的地方就是维护，但是很难做到新人能根据文档进行维护，文档不能代替沟通，没有人进行业务指导，系统很难维护，升级或者改造更困难，对于企业的业务系统而言，指望谁都可以按照文档进行维护是不可能的。

从上面技术文档的三个用途可以看出，技术人员的业务理解、沟通和技术能力是项目成败的关键，文档的作用没有想象的那么大，如果公司的人力资源出了问题，按照所谓的“工厂流水线”方式进行管理，把开发人员当作工具和螺丝钉，把人力资源当作成本来控制，想通过过程体系和文档标准来控制软件开发进度和质量，注定会失败。

后续（二、管理文档）

这种说法我是完全不同意的，你有这种想法是因为你没写过真正的实用文档。也是现在为什么国内这么多软件公司还是不写文档的原因。“设计在我的头里面，直接来问我吧”

我倒是很同意这段话的。越是沟通顺利的团队，越是不需要太多的文档。

另外，andyyehoo，能不能给出一份真正实用的文档的例子呀？咱们也学习学习。

业务系统的开发最关键的是业务流程和分析文档，用户手册也很重要，这方面的文档是必要的，怎么写就超出这篇帖子的内容了。

我的观点是如果沟通充分的话，只需要少量的文档就可以，文档不能代替沟通，看文档不如小组内外部的及时沟通，程序员的时间应该尽可能的用在程序开发上，这也是项目经理的职责。我们都反对过分设计，是因为过分设计是一种浪费，那么文档呢？不必要的文档也是一种浪费。我所面对的项目，一般的项目项目组都不超过4个小组，16名开发员，加上3－4名界面制作、2－3名业务顾问。

少些文档并不表示不写文档，很多情况下文档是可以想办法的，没必要先写文档后做开发，如果小组配合默契，有一套框架和方法，可能会跳过很多公司设定的阶段。

管理层希望通过文档来解决在项目中后期人员流动和人事变动情况下，使项目能正常进展的问题，实际效果我看很少有不延期的。

“设计在我的头里面，直接来问我吧”我不清楚这句话的场景，看什么文档？业务文档？框架设计？看文档是想干什么，是想检查？学习？维护？

文档？你说白皮书、项目规划、需求用例的话，我同意，这些文档是一定要写的，而且要认真写。没有白皮书就打不到标，没有项目规划就申请不到经费，没有用例就不知道该做些什么事情。还有用户故事，还有迭代计划，这些都是重要的文档，要用纸卡片写下来钉在墙上每天看三遍。

如果你说什么设计文档，我就说是扯淡。如果是基础框架，我还可以做得稳定了出一份应用手册方便大家学习（就像我给G-Roller框架写的应用手册）。如果是项目的设计文档，至少我是100%等项目做完了再写，写好给那些看不懂的人去看。维护人员和开发人员想知道我的设计？很简单，看单元测试。

文档就好比小孩的照片,自己生的宝宝不拍照片留做纪念,宝宝也能长大,拍了也能长大,文档就像日记,流水帐,不记也能生活,记了也还是生活;这是我的理解!

很好的比喻啊，呵呵。可惜孩子经常要给不同人养的，养的人不拍照片，接养的人就苦了

呵呵，还是那个问题，所以给不了。

“公司人员稳定、项目组内部团结、设计开发能力强、代码编写规范、项目规模不大”这种情况下，不写文档确实不存在太大问题，关键是，现在国内有多少公司能够满足这种条件呢？

我主张是文档也是XP的，一开始就写，不需要准确无误，但是就是把自己的思路整理出来，作为一个详细设计文档的初稿，做的过程中，需要修正的话慢慢改进。而不是一上来就写代码。即使测试用例，也不能代替文档，这是我的观点。

项目做完了，补做文档，其实是很不现实的，程序员懒了，公司也懒的。增量文档开发，才是现实的。当然，项目紧的话，一切都是扯淡，测试用例都不一定写的了，更无论文档了，呵呵。

呵呵，这个问题是我很关心的。我总是把它称为Effective Documentation，而且把它看成是Effective Communication的一个重要组成。
:P
Effective Documentation的最重要的一条就是何时需要文档。
交流的手段有很多，隐喻、讨论、面谈、使用文档……
要做到Effective Communication，我们就要在合适的地方使用合适的手段。
要决定Who和When，我们首先要理解What、How和Why。

隐喻经常出现，但是不是那么靠得住。如果在出现错误之后，当事人说：“我以为……”，这就表明在需要细致可靠的地方使用了隐喻这种不太靠得住的东西。

讨论和面谈都是性价比极高的东西。
它们的表现能力非常强，精确性也极高。人可以通过重音来强调自己想要表达的重点，比如“Mary had a black sheep”。文档也可以用字体、颜色等来强调，但是它没有针对性。比如针对“What an animal did mary have”，人会回答“A black sheep”，但是文档不会。
这是因为文档没有智能。在讨论和面谈中，交流的每一方都具有智能，这使得交流更加丰富和准确。继续上面的例子，如果再问“That is to say, Mary has nothing now?”，人就可以回答“Yes, what a poor gril!”，文档则完全没有办法直接回答。
之所以出现这些优点，我觉得本质的原因在于交流的载体和使用载体的方式上。
这里的载体是声音，这是一个极其廉价的载体，其成本可以看作0。而它的使用方式，严格遵守着“使用时创建，使用后抛弃”的原则。（呵呵，插一句，这种思想在对象的构造与析构上也是有指导意义的:P）这种使用方式降低了载体的地位，真正实现了智能双方的亲密接触。

使用文档的可靠性和稳定性最高。
文档这种载体的跨越时间和空间的可靠性和稳定性，是声音这种载体望尘莫及的。但是，目前看来，大部分的文档的成本都很高，因此很难做到“使用时创建，使用后抛弃”。部分ＣＡＳＥ工具能够降低某一些文档的成本，但是这些工具本身就非常昂贵。
对文档最常见的误用就是用来刻画随时变化的东西。我们有一个老掉牙的故事，叫做“刻舟求剑”，但是看来很多人对这个故事没有太深刻的理解。现在大部分的文档都跟独孤木说的一样，“记载的是历史上的某一天”。所以我们要注意文档的运用，借用侯Sir的话，“勿在浮沙筑高台”（呵呵，跟他书上原意完全不一样喔:P）。

楼上的文学修养好高啊，相信写作能力一定很强。
说实话，我的写作灌水能力一直停留在中学阶段，写的文档总是差强人意啊，呵呵