| 今天在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）。
| 
