軟件開發(fā)中文檔的編寫是一個不可缺少的環(huán)節(jié)，常見的如《需求分析》、《概要分析》、《數(shù)據(jù)庫設(shè)計(jì)》等。在“軟件人”的陣營里向來存在兩種觀點(diǎn)，注重文檔還是關(guān)心代碼。一直爭論多少年了，好像都沒有一個真正的定亂。如果大項(xiàng)目且開發(fā)周期相對合理，很多時(shí)候項(xiàng)目組一定會安排進(jìn)行相關(guān)開發(fā)文檔的編寫；但對于周期短工作量又多的時(shí)候，可能很多項(xiàng)目組就會選擇代碼編寫為第一的原則，相應(yīng)的文檔編寫很多時(shí)候被安排在項(xiàng)目演示甚至交付后才進(jìn)行補(bǔ)救式的操作，而且這樣的文檔很多都是歸于應(yīng)付客戶要求的形式罷了。

項(xiàng)目周期與質(zhì)量保證向來是相矛盾的，如果為了保證質(zhì)量消耗時(shí)間去編寫文檔，必將壓縮系統(tǒng)開發(fā)的時(shí)間；不進(jìn)行開發(fā)文檔的編寫，又沒法進(jìn)行開發(fā)質(zhì)量的保證。那問題就來了，開發(fā)文檔是否需要編寫？怎么寫？誰來寫？

首先，我們來討論下開發(fā)文檔編寫的必要性，即要不要編寫開發(fā)文檔；這些開發(fā)文檔是否就一定能在開發(fā)中指導(dǎo)我們的程序員編寫代碼；在運(yùn)維中支撐維護(hù)人員解決問題等。

“高樓萬丈平地起”，這里告訴我們，一座高樓是否可以建？怎么建？建多高？最終由地基來決定。沒有地基的牢固支撐，你建的樓就會變成“低樓”、“危樓”、“爛尾樓”。高樓需要地基的存在，需要地基的支撐，沒有這兩樣又想要高樓，那只有去找“空中樓閣”了。那這個地基的牢固與否又是靠什么東西決定呢？“設(shè)計(jì)圖紙”，對就是設(shè)計(jì)圖紙，沒有圖紙上專業(yè)化的設(shè)計(jì)和演算規(guī)劃，創(chuàng)建牢固的地基那就是天方夜譚、癡人說夢。

回到我們的軟件項(xiàng)目中來，一個項(xiàng)目的成功同樣需要一個牢靠的地基，有了這個地基才能裝載那些各付其職的功能模塊。這個地基就是我們軟件的《架構(gòu)設(shè)計(jì)》和《概要設(shè)計(jì)》，沒有架構(gòu)的設(shè)計(jì)就不能確保整個系統(tǒng)穩(wěn)定的運(yùn)行與統(tǒng)一處理方式等；沒有概要設(shè)計(jì)，客戶怎么知道當(dāng)前需要能完成那些功能，程序員又如何得知自己編寫的功能模塊針對的業(yè)務(wù)處理流程，當(dāng)然更不可能保證數(shù)據(jù)邏輯處理的正確性、完整性。不用再討論下去了吧，光這兩個問題，就能足以說明文檔編寫的重要性了。

       看到這里你可能會里面跳出來駁斥我的謬論，理直氣壯般告訴我，我們的項(xiàng)目沒有《架構(gòu)設(shè)計(jì)》和《概要設(shè)計(jì)》也做的很好啊。我們是沒有《架構(gòu)設(shè)計(jì)》，因?yàn)槲覀儔焊鶅壕筒恍枰覀兊募軜?gòu)已經(jīng)是多年成型的東西，很完美，進(jìn)行了不同層次的封裝，提供了豐富多樣的擴(kuò)展接口。有了這樣成熟的系統(tǒng)架構(gòu)而且是已經(jīng)實(shí)現(xiàn)的東西，為什么我們還需要《架構(gòu)設(shè)計(jì)》，莫名其妙。我相信你說的這些，你們的架構(gòu)很完美，相當(dāng)健壯，可擴(kuò)展性又豐富，我承認(rèn)這些都是好框架必須具備的，你們的框架也是好框架。但我能否問下，你們的這個完美是如何誕生的？如果是公司內(nèi)部自行研發(fā)的，那敢肯定一定存在設(shè)計(jì)文檔；如果是某個牛人自己磨練出來的，那就有點(diǎn)擔(dān)心了，萬一這個牛人走了如何是好？難道你們告訴客戶，我們的架構(gòu)有問題，不做這個項(xiàng)目了？夸張！！！我又問，你們的這個完美是否存在缺陷？如果你說不存在，那我只能伸手?jǐn)[個pose，鄙視你的年幼無知，如果你說存在但是不知道，那我只能送你兩個字——“杯具”；我最后問，你們的這個完美是否可以兼容所有的企業(yè)運(yùn)用？是否能支持J2EE、J2ME、J2SE的解決方案？要是你告訴我說僅支持J2EE，因?yàn)槲覀冎蛔?/span>J2EE的項(xiàng)目。你是老板嗎？說這樣的要負(fù)責(zé)任的，不然被老板聽見，小心砸你飯碗。

       說完文檔編寫的必要性，那就來說說如何寫的問題。其實(shí)很多時(shí)候一個成熟的軟件公司或項(xiàng)目組都會有一套成型的文檔模板，當(dāng)然這些模板很多可能是從化為、東軟等大型軟件公司變種出來的。有了這些定型的模板，那編寫文檔的工作就會輕松很多，我們需要做的就是在相應(yīng)的模板中填充自己的相關(guān)描述，即可形成針對當(dāng)前項(xiàng)目的開發(fā)文檔。

還是舉例說下吧，看上面的文字多少有點(diǎn)空泛，我這里寫一個《用戶信息模塊的概要設(shè)計(jì)文檔》，只列舉主要內(nèi)容了(僅供參考)。

1 功能描述：用于完成系統(tǒng)用戶信息的新增、刪除、修改、查詢；

2 功能用例：一個主用例用戶信息，附加新增、刪除、修改、查詢4個子用例，操作人員為管理員，圖形就不畫了，很簡單的；

3 業(yè)務(wù)流程：查詢有效范圍用戶信息——》新增用戶信息——》判斷當(dāng)前帳號是否存在——》存在給出提示，反之保存成功提示。（簡單的說下，圖形就不畫了）

4 約束限制：

超級管理員可操作所有（包含刪除，我這里考慮僅是邏輯刪除、非物理刪除）的用戶信息；

系統(tǒng)管理員可操作除系統(tǒng)管理員、超級管理員外的全部用戶信息；

單位管理員可操作本單位用戶信息；

用戶帳號信息系統(tǒng)內(nèi)全局唯一；

5 系統(tǒng)性能：

要求同時(shí)支持500個并發(fā)操作；

頁面操作響應(yīng)時(shí)間小于1s；

頁面大小小于1kb；

當(dāng)前用戶所屬員工信息不存在時(shí)，可直接進(jìn)行員工信息的添加，并完成用戶信息的同步保存，確保事務(wù)的完整性；

6 運(yùn)行環(huán)境：依賴系統(tǒng)整體運(yùn)行環(huán)境為準(zhǔn)（存在特殊需要注明）；

7 操作實(shí)體：用戶信息、員工信息、系統(tǒng)日志等（我不知道，大伙在除概要設(shè)計(jì)時(shí)候是否已完成數(shù)據(jù)庫/實(shí)體設(shè)計(jì)了。）；

8 異常處理：如果系統(tǒng)框架中已經(jīng)提供相關(guān)說明，這里僅需要注明符合系統(tǒng)架構(gòu)異常處理方式即可。

9 外部接口：輸入——用戶ID，輸出——用戶信息；

10 其他說明：用戶帳號必須定義為字母開頭，數(shù)字與字母組合，并保證全局唯一；用戶密碼采用md5算法加密，系統(tǒng)架構(gòu)已提供相關(guān)接口。

11 注意事項(xiàng)：用戶帳號不能為空，不能存在空格，不能超過6位；超級用戶信息僅在系統(tǒng)初始化中完成其信息寫入操作，其他用戶無權(quán)對其進(jìn)行修改；

羅列幾個文檔的要素，這些我覺得是你的模板一定需要定義的：

1 變更版本記錄、參考文獻(xiàn)、編寫人員、審核人員等；

2 制作背景、使用范圍、文檔作用；

3 文檔結(jié)構(gòu)描述、綱要描述、目錄描述；

4 輔助編寫工具（如viso\rose等建模工具都可以畫用例圖，但只能選擇一種）、文檔格式（word、 pdf還是其他）統(tǒng)一。

       項(xiàng)目組中也不是所有人都必須參與文檔的編寫，通常業(yè)務(wù)需求人員、設(shè)計(jì)人員、架構(gòu)師、項(xiàng)目經(jīng)理、小組長占大多數(shù)，而且這些人中很多也不是專注于寫代碼的角色。這就是項(xiàng)目組內(nèi)部分工協(xié)作的事情了，畢竟最大限度地發(fā)揮項(xiàng)目組各成員的綜合能力才是最主要的，“各司其職，各負(fù)其責(zé)”方是上策。

因?yàn)槲疫@里說的僅是開發(fā)文檔，所以像《用戶手冊》、《培訓(xùn)計(jì)劃》、《驗(yàn)收計(jì)劃》、《安裝步驟》等就沒羅列了。不是說它們不重要，只因?yàn)樗鼈儾粚儆陂_發(fā)文檔的范疇罷了。實(shí)際開發(fā)中，需要完成什么樣的文檔完全取決于當(dāng)前項(xiàng)目的開發(fā)、實(shí)施背景和用戶需求，有些文檔本就是做給客戶驗(yàn)收的。（我曾經(jīng)做一個電子政務(wù)系統(tǒng)，甲方請了監(jiān)理公司在實(shí)施過程中參與，結(jié)果搞得各式各樣的文檔都需要完成，盡管其中很多都是些形式東西，但沒法子，客戶就是上帝。）對于客戶要求這類型的文檔我們不一定要做細(xì)、做專，做體面才是最有效的。反之，對于項(xiàng)目開發(fā)中特別是代碼編寫的指導(dǎo)文檔，就必須要求編寫得簡單明了，面面俱到。

 （注：本人文章均為原創(chuàng)，轉(zhuǎn)載請注明出處！20100619寫于深圳。）