我对文档的要求：必要的、最小的冗余

    软件文档究竟应该怎么写？写多细？要不要写？有很多不同的看法。有人认为文档应该完备和优雅，并且总是应该用作下一个阶段的驱动；有人认为文档是要写的，但不必区分文档性质，文档间的组织结构也无所谓；有人则认为文档除了浪费时间之外没有任何意义，尤其在中国这个以“中档质量低档价格”的营销环境下，文档只会影响快速交付，降低竞争力，最终让股东很不高兴。

     我个人的观点是：文档应该用作代码的 必要的、最小的冗余。也就是说，
         1.文档是代码的冗余，因为文档里有的东西，代码里其实都有
         2.这个冗余是必要的，否则无法保障软件质量
         3.冗余应该是最小的，否则它会项目进度，并且让项目成员很不快乐

    
     首先，文档里的东西代码里都有，这个不必说。
     既然文档是冗余的东西，是不是应该去掉？ 如果项目成员能够牢记功能和代码的对应关系，并且能够飞速地扫描代码找到自己所需要的东西，那文档的确可以去掉；否则，还是应该把某些东西成文归档，记个笔记，尤其是需求文档，它是软件产品的最终参考，并且充当了需求人员和开发人员之间的契约，必须做的完备。


     但是，中国的软件公司都有普遍现状：文档超乱！最主要的原因有：
        1.项目太紧，没时间写
        2.文档格式很臃肿，不想碰它
        3.文档评审很麻烦
        4.我习惯在编码的过程中把设计做好，不想先写文档
        5.更新文档，有一种返工的感觉，超烦

     所以，要尽量在质量和进度以及烦恼指数上达到平衡。我的建议是，只写“最小的”文档。它包括：
        1.文档工作量尽量地少。我只觉得三个文档是必须的：需求规格说明书，概要设计文档和测试用例。而且，概要设计文档没必要太细致。
        2.抛弃文档模板，只写有必要写的东西。现在很多设计文档里都喜欢把“需求背景”复述一便，换了我写一个“略”字带过
        3.确立开为人员作为文档的主导者，改了代码后自己迅速修改文档，由于自己熟悉文档，在评审时也可以与业务分析人员迅速沟通。
        4.完全可以在开发完成后再补充文档。你完全可以在快速编码的过程中通过调试实现最优设计，这种设计往往比预先的设计要少很多漏洞。
        5.文档不要再建副本。一个组织就一份文档，其版本通过版本工具来维护，不要用邮件发来发去，副本太多是引发混乱的前奏。

"文档是代码的冗余，因为文档里有的东西，代码里其实都有"
-- 一些设计思想在还没开始coding的时候哪里来的代码？

文档更多的时候是个过程：思考＋交流

希望能尽快出现山寨版的Telelogic Doors。

用Word做文档那叫一个痛苦。

互为冗余嘛，谁先谁后不重要

似曾相似
好像在匠艺里面有看过
不过实话实说，做什么事情都要有依据
能回答老板的凭什么就成功一半了

只想问一下，在软件没有开发出来之前，你认为必要的测试用例从哪里来。

测试用例应该在编码之前就完成主要轮廓，以此来保证之后开发的代码都必须能通过测试用例的测试。
如果在代码完成后再写测试用例，不仅沦为形式，而且还容易“下意识”的绕开某些问题。

正所谓是代码未动，测试先行。

我不太懂国内开发，只是有个问题不明白。
没有文档的话，项目管理是如何做的？
靠项目经理的脑子吗？

很小的项目，并且代码注释很详细（可能性，可行性？）或许可以考虑下；

"文档里的东西代码里都有，这个不必说";
不太理解！

一个业务可以有多种对应实现方式，一段代码或许只是针对该业务的一种实现方式？

导致混乱的还有个关键问题是文档和代码太分离，联系不紧密，看到一个功能找相应的文档也方便。在我们公司自行研发的框架中，要求文档是内嵌在系统中的，任何有相应权限的人打开系统的任何一个功能，可以随时去编辑，查看相应类型的文档。