| 今天在javaeye上看到一篇文章，讨论文档的价值。忍不住就回了一帖。 考虑到打那么多字不容易，最近又一直没有写blog，所以贴到这里来，算是冒个泡泡，表示我还活着吧。 ![13.gif]() 呵呵，这个问题是我很关心的。我总是把它称为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）。
| 
