文档的价值？

这个也是很多人不愿意写文档和看文档的原因。近期来看，与其去花一个小时写一篇文档和其它人花半个小时读文档，不如坐下来面对面的谈上15分钟有效。有时候明明写了文档，同事确不愿意看，还是跑过来，要你手把手演示讲解，非常打击写文档积极性。

可是，这种看文档的功力和写文档的功力，是利用人家开源项目和自己做开源项目必不可少的功力啊，所以，我有机会还是会多锻炼自己这种能力，如果项目时间允许的话。

hehe，如果是可以随时跑过来面对面交流的场合，为什么不好好利用呢？
：P
我通常的做法是写一个极粗的备忘录，然后拿这个去给需要知道这些信息的人讲解、讨论，把信息push到他们的脑袋里边去。通过询问“说说你的理解”，可以初步确认他们接受的程度。遗漏的细节问题，通过实际运用和“无情的测试”中会暴露出来，到时候可以再次交流。
为了避免多次就同一个问题说明，做个FAQ是个好办法。FAQ与一般文档不同，它是一种针对性很强的文档。因此它的效率也比较高。

至于开源对于文档的需要，其根本原因，我想是开源的开发者无法应付巨大数目的提问，所以需要写一份广泛适用的文档。
对于特定的问题，他们也是允许通过mail来做针对性的交流的。
而在特定的几个伙伴之间，则会使用一些实时通讯的工具——QQ、MSN——来交流。

说到培养写文档的能力，我倒觉得先练练面对面交流比较好。
正如前面所说，文档这东西是没有智能的。因此，写完文档之后，没有办法马上知道写的好不好。
面对面交流不一样，如果你解释的不好，从对方一脸的迷惑上就能看出来。于是你可以调整自己的说明方式，询问对方的理解情况，最终把问题说清楚。
这种方式对你自己的提高是很明显的。
在频繁的反馈之后再写的文档，一定比一开始就写的文档准确、易懂。

呵呵，顺便插一句，我觉得线性过程的最大弊病就是反馈不及时。在分析/设计中埋下的地雷要到几个月之后才能发现，这样的项目怎么可能不delay。现在的短周期迭代的开发模式缩短了反馈的周期，而TDD则更是要求实时反馈。
呵呵，说了这么多，有班门弄斧的嫌疑，见笑、见笑。
：P

相对文学修养写作能力而言，写技术文档对逻辑思维的要求更高些。用最朴实的话（越朴实越好）把一个问题或者一个框架描述明白就行了。

说到面对面交流，并不是所有的项目都有这么好的条件，如果有这个条件，当然是问人要快些，而且由于人为原因文档总有很多滞后于实际的地方。但是谁也不能保证自己会一直呆在一个公司负责开发、维护某一个项目，一旦你走了，那么这个项目就需要别人来开发或者维护，就算有交接工作，也不可能完全说的明白，这时候，文档就变的异常关键了。当然还有代码和注释，不知道这些算不算文档一类？

why没有需求文档，我觉得需求文档才是最重要的，
开发，我觉得有模型，有写得好的注释，javadoc，文档到不一定要有。

我觉得这里的问题是，如果你这里有需求文档、设计文档和开发文档(直接在javadoc中)，怎么保证它们的同步性。
不同步的文档比没有文档更加困难，因为它有一个误导作用，使别人在自以为正确的基础上作一些很可能没有意义的事情。
对于需求文档，我觉得这里还有一个内容和表现形式的问题。针对不同的人，对于同一个过程的不同侧面，都需要有不同的表现方式。问题在于怎样以一种一致的方式来编写这个文档，使其能够通过简单的转换(如xsl之于xml)，就能够得到某一个方式的表现。否则的话，又要处理不同表现的同步问题。
我觉得现有的工具都是针对开发者的，而不太适用于最终用户。拿一个uml图远不如手工编制一个能够达意的东西来的清楚。