軟件開發中文檔的編寫是一個不可缺少的環節，常見的如《需求分析》、《概要分析》、《數據庫設計》等。在“軟件人”的陣營里向來存在兩種觀點，注重文檔還是關心代碼。一直爭論多少年了，好像都沒有一個真正的定亂。如果大項目且開發周期相對合理，很多時候項目組一定會安排進行相關開發文檔的編寫；但對於周期短工作量又多的時候，可能很多項目組就會選擇代碼編寫為第一的原則，相應的文檔編寫很多時候被安排在項目演示甚至交付后才進行補救式的操作，而且這樣的文檔很多都是歸於應付客戶要求的形式罷了。
項目周期與質量保證向來是相矛盾的，如果為了保證質量消耗時間去編寫文檔，必將壓縮系統開發的時間；不進行開發文檔的編寫，又沒法進行開發質量的保證。那問題就來了，開發文檔是否需要編寫？怎么寫？誰來寫？
首先，我們來討論下開發文檔編寫的必要性，即要不要編寫開發文檔；這些開發文檔是否就一定能在開發中指導我們的程序員編寫代碼；在運維中支撐維護人員解決問題等。
“高樓萬丈平地起”，這里告訴我們，一座高樓是否可以建？怎么建？建多高？最終由地基來決定。沒有地基的牢固支撐，你建的樓就會變成“低樓”、“危樓”、“爛尾樓”。高樓需要地基的存在，需要地基的支撐，沒有這兩樣又想要高樓，那只有去找“空中樓閣”了。那這個地基的牢固與否又是靠什么東西決定呢？“設計圖紙”，對就是設計圖紙，沒有圖紙上專業化的設計和演算規划，創建牢固的地基那就是天方夜譚、痴人說夢。
回到我們的軟件項目中來，一個項目的成功同樣需要一個牢靠的地基，有了這個地基才能裝載那些各付其職的功能模塊。這個地基就是我們軟件的《架構設計》和《概要設計》，沒有架構的設計就不能確保整個系統穩定的運行與統一處理方式等；沒有概要設計，客戶怎么知道當前需要能完成那些功能，程序員又如何得知自己編寫的功能模塊針對的業務處理流程，當然更不可能保證數據邏輯處理的正確性、完整性。不用再討論下去了吧，光這兩個問題，就能足以說明文檔編寫的重要性了。
看到這里你可能會里面跳出來駁斥我的謬論，理直氣壯般告訴我，我們的項目沒有《架構設計》和《概要設計》也做的很好啊。我們是沒有《架構設計》，因為我們壓根兒就不需要它，我們的架構已經是多年成型的東西，很完美，進行了不同層次的封裝，提供了豐富多樣的擴展接口。有了這樣成熟的系統架構而且是已經實現的東西，為什么我們還需要《架構設計》，莫名其妙。我相信你說的這些，你們的架構很完美，相當健壯，可擴展性又豐富，我承認這些都是好框架必須具備的，你們的框架也是好框架。但我能否問下，你們的這個完美是如何誕生的？如果是公司內部自行研發的，那敢肯定一定存在設計文檔；如果是某個牛人自己磨練出來的，那就有點擔心了，萬一這個牛人走了如何是好？難道你們告訴客戶，我們的架構有問題，不做這個項目了？誇張！！！我又問，你們的這個完美是否存在缺陷？如果你說不存在，那我只能伸手擺個pose，鄙視你的年幼無知，如果你說存在但是不知道，那我只能送你兩個字——“杯具”；我最后問，你們的這個完美是否可以兼容所有的企業運用？是否能支持J2EE、J2ME、J2SE的解決方案？要是你告訴我說僅支持J2EE，因為我們只作J2EE的項目。你是老板嗎？說這樣的要負責任的，不然被老板聽見，小心砸你飯碗。
說完文檔編寫的必要性，那就來說說如何寫的問題。其實很多時候一個成熟的軟件公司或項目組都會有一套成型的文檔模板，當然這些模板很多可能是從化為、東軟等大型軟件公司變種出來的。有了這些定型的模板，那編寫文檔的工作就會輕松很多，我們需要做的就是在相應的模板中填充自己的相關描述，即可形成針對當前項目的開發文檔。
還是舉例說下吧，看上面的文字多少有點空泛，我這里寫一個《用戶信息模塊的概要設計文檔》，只列舉主要內容了(僅供參考)。
1 功能描述：用於完成系統用戶信息的新增、刪除、修改、查詢；
2 功能用例：一個主用例用戶信息，附加新增、刪除、修改、查詢4個子用例，操作人員為管理員，圖形就不畫了，很簡單的；
3 業務流程：查詢有效范圍用戶信息——》新增用戶信息——》判斷當前帳號是否存在——》存在給出提示，反之保存成功提示。（簡單的說下，圖形就不畫了）
4 約束限制：
超級管理員可操作所有（包含刪除，我這里考慮僅是邏輯刪除、非物理刪除）的用戶信息；
系統管理員可操作除系統管理員、超級管理員外的全部用戶信息；
單位管理員可操作本單位用戶信息；
用戶帳號信息系統內全局唯一；
5 系統性能：
要求同時支持500個並發操作；
頁面操作響應時間小於1s；
頁面大小小於1kb；
當前用戶所屬員工信息不存在時，可直接進行員工信息的添加，並完成用戶信息的同步保存，確保事務的完整性；
6 運行環境：依賴系統整體運行環境為准（存在特殊需要注明）；
7 操作實體：用戶信息、員工信息、系統日志等（我不知道，大伙在除概要設計時候是否已完成數據庫/實體設計了。）；
8 異常處理：如果系統框架中已經提供相關說明，這里僅需要注明符合系統架構異常處理方式即可。
9 外部接口：輸入——用戶ID，輸出——用戶信息；
10 其他說明：用戶帳號必須定義為字母開頭，數字與字母組合，並保證全局唯一；用戶密碼采用md5算法加密，系統架構已提供相關接口。
11 注意事項：用戶帳號不能為空，不能存在空格，不能超過6位；超級用戶信息僅在系統初始化中完成其信息寫入操作，其他用戶無權對其進行修改；
http://www.cnblogs.com/roucheng/
羅列幾個文檔的要素，這些我覺得是你的模板一定需要定義的：
1 變更版本記錄、參考文獻、編寫人員、審核人員等；
2 制作背景、使用范圍、文檔作用；
3 文檔結構描述、綱要描述、目錄描述；
4 輔助編寫工具（如viso/rose等建模工具都可以畫用例圖，但只能選擇一種）、文檔格式（word、 pdf還是其他）統一。
項目組中也不是所有人都必須參與文檔的編寫，通常業務需求人員、設計人員、架構師、項目經理、小組長占大多數，而且這些人中很多也不是專注於寫代碼的角色。這就是項目組內部分工協作的事情了，畢竟最大限度地發揮項目組各成員的綜合能力才是最主要的，“各司其職，各負其責”方是上策。
因為我這里說的僅是開發文檔，所以像《用戶手冊》、《培訓計划》、《驗收計划》、《安裝步驟》等就沒羅列了。不是說它們不重要，只因為它們不屬於開發文檔的范疇罷了。實際開發中，需要完成什么樣的文檔完全取決於當前項目的開發、實施背景和用戶需求，有些文檔本就是做給客戶驗收的。（我曾經做一個電子政務系統，甲方請了監理公司在實施過程中參與，結果搞得各式各樣的文檔都需要完成，盡管其中很多都是些形式東西，但沒法子，客戶就是上帝。）對於客戶要求這類型的文檔我們不一定要做細、做專，做體面才是最有效的。反之，對於項目開發中特別是代碼編寫的指導文檔，就必須要求編寫得簡單明了，面面俱到。
（注：本人文章均為原創，轉載請注明出處！20100619寫於深圳。--刀光劍影）