我对文档的要求：必要的、最小的冗余
软件文档究竟应该怎么写？写多细？要不要写？有很多不同的看法。有人认为文档应该完备和优雅，并且总是应该用作下一个阶段的驱动；有人认为文档是要写的，但不必区分文档性质，文档间的组织结构也无所谓；有人则认为文档除了浪费时间之外没有任何意义，尤其在中国这个以“中档质量低档价格”的营销环境下，文档只会影响快速交付，降低竞争力，最终让股东很不高兴。
我个人的观点是：文档应该用作代码的 必要的、最小的冗余。也就是说，
1.文档是代码的冗余，因为文档里有的东西，代码里其实都有
2.这个冗余是必要的，否则无法保障软件质量
3.冗余应该是最小的，否则它会项目进度，并且让项目成员很不快乐
首先，文档里的东西代码里都有，这个不必说。
既然文档是冗余的东西，是不是应该去掉？ 如果项目成员能够牢记功能和代码的对应关系，并且能够飞速地扫描代码找到自己所需要的东西，那文档的确可以去掉；否则，还是应该把某些东西成文归档，记个笔记，尤其是需求文档，它是软件产品的最终参考，并且充当了需求人员和开发人员之间的契约，必须做的完备。
但是，中国的软件公司都有普遍现状：文档超乱！最主要的原因有：
1.项目太紧，没时间写
2.文档格式很臃肿，不想碰它
3.文档评审很麻烦
4.我习惯在编码的过程中把设计做好，不想先写文档
5.更新文档，有一种返工的感觉，超烦
所以，要尽量在质量和进度以及烦恼指数上达到平衡。我的建议是，只写“最小的”文档。它包括：
1.文档工作量尽量地少。我只觉得三个文档是必须的：需求规格说明书，概要设计文档和测试用例。而且，概要设计文档没必要太细致。
2.抛弃文档模板，只写有必要写的东西。现在很多设计文档里都喜欢把“需求背景”复述一便，换了我写一个“略”字带过
3.确立开为人员作为文档的主导者，改了代码后自己迅速修改文档，由于自己熟悉文档，在评审时也可以与业务分析人员迅速沟通。
4.完全可以在开发完成后再补充文档。你完全可以在快速编码的过程中通过调试实现最优设计，这种设计往往比预先的设计要少很多漏洞。
5.文档不要再建副本。一个组织就一份文档，其版本通过版本工具来维护，不要用邮件发来发去，副本太多是引发混乱的前奏。 1 楼 iamredeye 2009-01-09 "文档是代码的冗余，因为文档里有的东西，代码里其实都有"
-- 一些设计思想在还没开始coding的时候哪里来的代码？
文档更多的时候是个过程：思考＋交流 2 楼 cyberblue 2009-01-10 希望能尽快出现山寨版的Telelogic Doors。
用Word做文档那叫一个痛苦。 3 楼 chenjianjx 2009-01-13 互为冗余嘛，谁先谁后不重要
iamredeye 写道
-- 一些设计思想在还没开始coding的时候哪里来的代码？
4 楼 nonocast 2009-01-19 似曾相似
好像在匠艺里面有看过
不过实话实说，做什么事情都要有依据
能回答老板的凭什么就成功一半了 5 楼 鹿鸣 2009-02-17 只想问一下，在软件没有开发出来之前，你认为必要的测试用例从哪里来。 6 楼 vlinux 2009-02-18 鹿鸣 写道只想问一下，在软件没有开发出来之前，你认为必要的测试用例从哪里来。
测试用例应该在编码之前就完成主要轮廓，以此来保证之后开发的代码都必须能通过测试用例的测试。
如果在代码完成后再写测试用例，不仅沦为形式，而且还容易“下意识”的绕开某些问题。
正所谓是代码未动，测试先行。 7 楼 czqyr 2009-02-18 我不太懂国内开发，只是有个问题不明白。
没有文档的话，项目管理是如何做的？
靠项目经理的脑子吗？ 8 楼 PowerNTT 2009-02-27 很小的项目，并且代码注释很详细（可能性，可行性？）或许可以考虑下；
"文档里的东西代码里都有，这个不必说";
不太理解！
一个业务可以有多种对应实现方式，一段代码或许只是针对该业务的一种实现方式？
9 楼 bruceyao 2009-03-02 导致混乱的还有个关键问题是文档和代码太分离，联系不紧密，看到一个功能找相应的文档也方便。在我们公司自行研发的框架中，要求文档是内嵌在系统中的，任何有相应权限的人打开系统的任何一个功能，可以随时去编辑，查看相应类型的文档。 10 楼 pipilu 2009-03-02 bruceyao 写道导致混乱的还有个关键问题是文档和代码太分离，联系不紧密，看到一个功能找相应的文档也方便。在我们公司自行研发的框架中，要求文档是内嵌在系统中的，任何有相应权限的人打开系统的任何一个功能，可以随时去编辑，查看相应类型的文档。
这个东西不错啊。 11 楼 chenjianjx 2009-03-03 非常同意！
而且你们的这个框架也很牛逼！
bruceyao 写道
导致混乱的还有个关键问题是文档和代码太分离，联系不紧密，看到一个功能找相应的文档也方便。在我们公司自行研发的框架中，要求文档是内嵌在系统中的，任何有相应权限的人打开系统的任何一个功能，可以随时去编辑，查看相应类型的文档。
12 楼 zhouxg0105 2009-12-18 1.文档工作量尽量地少。
数据库设计文档都不要了？
2.“需求背景”“略”字带过
来新人维护怎么办？
3.改了代码后自己迅速修改文档
有几个人愿意后补文档？
4.完全可以在开发完成后再补充文档。你完全可以在快速编码的过程中通过调试实现最优设计，这种设计往往比预先的设计要少很多漏洞。
都没想好编什么码？
5.其版本通过版本工具来维护
同意 13 楼 charles751 2009-12-18 文档的多与少，应该写到什么程度，和项目的性质紧密相关，另外和项目的重要性也有关系。
如果是公司自己的项目，视项目的重要性可相应地调整文档内容和厚度。
一般文档只要能描述清楚需求，写好详细设计,便于日后系统的升级和优化就可以了。
但如果是系统集成项目，文档没有厚度，中标可能性会大大降低。
做系统集成的公司大多有个可笑的场景，同事见面了寒暄几句都在做什么项目，接下来第一句就是，文档写了多少页啊，没个500页以上说的人都不好意思，因为在这个行业里，好像一般8，900页才刚及格，一个项目1000几百页文档很常见，但真正能起到指导实施的内容，也许只有几十页有点意思，大多是实施的时候前期的设计文档都被废弃了。
是可笑还是悲哀，但这就是现实。 14 楼 Durian 2009-12-21 敏捷开发模式不需要文档。
几个人聚在一起就研究需求，在白板上画出uml草图，继续研究，再修改，在画，打印下来或者数码相机拍照留档。
尤其强调，uml图是为了交换意见而用，不作为文档内容。
