文档，重要？不重要？有多重要？

环境决定一切....

最近一个项目，写文档的时间远大于写代码的时间，项目发布到集成测试环境后，代码基本上没太多改动了，文档倒是改个没停。

需求文档，设计文档，用户手册...，最难的是用户手册，这是项目的面子工程，直接涉及到集成测试的复杂度和代价，象我们这个WebService,天南地北的不知道会被谁用到，一个一个用户去解释实在招架不住，于是昨天改了，今天接着改....

评论

21 楼 JavaInActoin 2006-11-08  

项目达到相当规模时，文档是必需的，但是不要涉及过多的细节，细节性的东西代码已经表达了。文档是代码的一种补充，突出重要问题，隐藏掉代码中的细节。对于一般问题，文档的可读性和阅读效率高于代码。文档作为一种索引，在需要了解细节时，可以快速定位至相关代码的位置。

20 楼 pedestrian_I 2006-11-07  

adamzhao 写道

除了需求文档，概要设计文档，用户手册之外，其他的（如详细设计）似乎并不重要，而且最要命的无法同步更新，形同鸡肋。

还是XP好呀

需求文档，概要设计文档，用户手册这三个的确非常重要，用户手册是面子工程，需求文档和概要设计文档是里子工程。
那么详细设计文档是里子的里子了，程序员写代码都是通过它来指导的。
如果说详细设计文档没有或者是乱来的，那么这个项目前期的规划肯定也是乱的，设计上不下功夫，到时候写出来的代码是五花八门。
需求文档，概要设计文档，用户手册，详细设计文档是项目文档中必不可少的。

19 楼 抛出异常的爱 2006-11-07  

风雪涟漪 写道

只要客户给钱 给时间 ,写一年又有什么

那是给自己的方便关客户什么事?
维护时哭天天不应叫地地不灵.

18 楼 noble 2006-11-07  

越做项目，越重视文档。
当然，这不是指的形而上学的文档。

17 楼 风雪涟漪 2006-11-06  

只要客户给钱 给时间 ,写一年又有什么

16 楼 dongbin 2006-11-06  

代码可以通过Unit test来verify, 详细设计文档可以么？

只有写不出好代码的人，写不出Unit test的人才注重详细设计文档。因为文档写的好不好没有人说的清楚。

东郭先生也是这么想的。

15 楼 adamzhao 2006-11-02  

除了需求文档，概要设计文档，用户手册之外，其他的（如详细设计）似乎并不重要，而且最要命的无法同步更新，形同鸡肋。

还是XP好呀

14 楼 mickeybaobao 2006-11-02  

我觉得写文档真的是很重要的，特别是对中途加入项目组的开发人员来说，很有帮助的，我深有体会，好多需求什么的都只能通过文档来了解了

13 楼 husthxd 2006-09-15  

对于业务系统开发而言,
对内:str(业务需求文档)和srs(系统需求文档)是最为重要的.
对外:前面的xd提到的,用户手册/培训文档等.

12 楼 yhc0125 2006-09-14  

个人认为文档还是很重要的，特别是对于大型长期的项目。

11 楼 jianfeng008cn 2006-09-13  

number017 写道

我现在项目组的项目经理是一位大学里面的知名教授，言必称对象，整天自己趴在那边写文档，然后交给下面人开发。底下人也不敢去问他，因为他很会骂人，结果很多误导。概要设计、详细设计...其实都是一堆垃圾。开发人员谁也不会去看那个。典型的文档驱动开发。结果是项目一推再推，而那位教授，也把责任推给其他人，因为他是知名的。唉...

我认为有用的文档包含用户手册（这个相当重要，拿给客户直接可以看出你专业不专业）。还有一份比较简洁的技术说明或者业务介绍，每个新来的同事看这份文档就可以比较快速的，或者是有帮助的融入进来。

好象很有趣哦 这样的文档我很想看到呢

10 楼 evanyuan 2006-09-13  

温柔一刀 写道

写文档狠枯燥累人

写代码的能力，在公司里面不容易体现出来，因为一般没人去看你的代码，只有等你走了以后，维护的人会去看，写得好的话他受益； 写文档的能力，就比较容易体现出来些，在开发过程中你上面的人及你的开发伙伴基本上都会看看的。 是有点个人功利的思想，但这不是大部分的现状么？


当然，文档要与否要看其必要性，必要性是由环境决定的。 如果只是应付什么审计，或者没有什么可预见的读者，那自然很枯燥，其质量和功效也别指望高到哪里去。

9 楼 number017 2006-09-13  

我现在项目组的项目经理是一位大学里面的知名教授，言必称对象，整天自己趴在那边写文档，然后交给下面人开发。底下人也不敢去问他，因为他很会骂人，结果很多误导。概要设计、详细设计...其实都是一堆垃圾。开发人员谁也不会去看那个。典型的文档驱动开发。结果是项目一推再推，而那位教授，也把责任推给其他人，因为他是知名的。唉...

我认为有用的文档包含用户手册（这个相当重要，拿给客户直接可以看出你专业不专业）。还有一份比较简洁的技术说明或者业务介绍，每个新来的同事看这份文档就可以比较快速的，或者是有帮助的融入进来。

8 楼 温柔一刀 2006-09-13  

写文档虽然有时候觉得狠枯燥累人
但一定要做
还必须得认真的做

7 楼 jichongchong 2006-09-13  

无法想象如果structs没有那么多的文档的话，是否还会流行。
最近用的框架正为文档少而苦恼呢。

6 楼 evanyuan 2006-09-12  

补充一点，我们这个算个中间层吧，用户不是Business User, 而是上面一层Development team。所以这个用户手册实际上是WebService的描述文档，因为会被很多不同的Team用到，所以文档就比较重要了。我觉得如何向别人介绍一个服务，确实是件很讲究的事情。我们也用到了一些Third Party的服务，比如PayPal(贝宝)，他们提供的文档（包括client example project)就体现了他们的专业程度，让人蛮触动的。


至于需求和设计文档，因为都是长期的项目，人员来来往往的，环境又特别复杂，而每个项目又只是更大的一个项目的一部分。所以当一个新人进来的时候，很难指望旁边的人把什么都讲给你听，只有通过查看大量的文档来了解系统的历史和现状。虽然可以察看Code,但是要知道逻辑可能散落在好几个系统里面，或者在数据库中，或者配置文件中，或者有些让人很难理解的定制逻辑，实在还是希望有高质量的文档。

可能，国内大部分人都是在做新项目的开发，对承包方来说最好是早点完工收钱，反正又不要我维护，即使要我维护那也要另外记时收钱，文档的重要性就没有体现得那么明显。但对使用软件的企业本身来说，就不得不考虑维护的成本，不管是自己做还是外包给别人做，我觉得都需要好好验收下文档。

5 楼 tianxinet 2006-09-12  

evanyuan 写道

...写文档的时间远大于写代码的时间...

现在多种软件过程都有这个问题，写“功能代码”的时间都只占少数

evanyuan 写道

...最难的是用户手册，这是项目的面子工程，....

这可不是什么“面子工程”，这是实打实的“里子工程”，一定要做好。

4 楼 buaawhl 2006-09-12  

用户手册当然重要。
辛苦做出来了，不就是希望卖得好吗。
用户手册是用户体验、用户服务的很重要的方面。

不过，看来，楼主的公司或者开发资源很丰富，或者对这个项目很重视，还专门拨给开发人员比开发更长的时间写用户文档，修缮项目文档。

3 楼 抛出异常的爱 2006-09-12  

开发人数越多
文档就应该越详细

“写文档的时间远大于写代码的时间”

是很正常的事。。。
就如同发射火箭一瞬
造火箭1年
研究10年

写文档让别人拿钱用了一生时间。。。。


刚刚看到的以前的贴子
http://www.iteye.com/topic/5876

2 楼 zjxiongmao 2006-09-12  

文档也是一种程序。。。