文檔要怎麼寫？

標籤：文檔

題記：今天立秋了，明天永遠是美好的一天

情境

    最近給營運人員寫了一份部署三個項目的文檔，由於系統需要和其他兩個系統互動，所以在配置方面複雜了些，尤其是對xml檔案地址配置這塊，經常出問題。當準系統實現的時候，給營運人員去部署的時候，寫文檔不單單是給別人寫，更多的是給自己寫。寫的過程中思路清晰了，一切都會變得明朗起來，有一種山窮水複疑無路，柳暗花明又一村的感覺，並且一下子把需要大腦中記憶的這些事情全部轉移到了文字上，一個字，舒服~，就像清理了電腦中的垃圾空間一樣。

    不過當我把寫好的文檔實際上去交給營運人員，營運人員需要根據文檔去部署，去配置的時候，發現自己寫的還是不夠細緻，有的地方自己能懂，但是他人卻很難消化，並且還需要來問我。那些文檔的時候要怎麼寫呢？大概總結如下，願大家指教。

文檔的本質?

    文檔不能光顧著結構清晰，文檔好看，而是要去想用什麼形式寫更易懂，哪些地方不用詳細，哪些地方必須詳細，必須多說幾句的，哪些地方是不容改變，哪些地方需要根據伺服器位址來靈活改變的，等等。應該迎合閱讀者的思維，理解過程來寫，最好是能用圖就先用圖把大概的關係寫出來。

文檔面對的對象?

    在下手寫文檔的時候，還是需要確定好文檔是寫給誰的，是針對哪個使用者來寫的文檔，在一開始弄cas這塊就要求寫文檔，當我在不知道具體是哪個使用者使用的前提下寫出的文檔，對於營運人員來說根本就用不了，所以就廢掉了，所以一定要針對的對象來寫。

啥時需要些文檔？

    我認為我們既不能思想上全部文檔化，因為寫文檔是一件耗時的事情，而且改動文檔的版本也需要花費大量的時間，所以一定要斟酌哪些需要文檔。我認為寫文檔的最終目的也是為了提高效率，減少了人與人之間溝通的時間，解放大腦，解放人力，從這個角度來衡量一件事情是否需要些文檔。

不重視結構？重視結構？

    雖然文檔的結構樣式是不必要的，就我們總是說一個人的外貌是不重要的，但是看到美女廣大男士們還是垂涎欲滴的。所以對於勤勞的程式猿們來說，看一份爽爽的文檔還是十分有必要的，從看文檔的使用者角度出發，怎麼方便使用者怎麼來，結構的設定，排版設定，字型的設定，一段話是否表達了一個中心意思等。

    大概的想到這些，望大家指教。O(∩_∩)O~

    序：

  

                                         生若夏花之絢爛 死若秋葉之靜美