在寫本系列的過程中，了解得越多越不知道從哪里做為切入點來寫，幾乎每個知識點展開來說都可以寫成一本書。而自己在寫作與文檔編寫方面來說，還是一個初鳥級別，所以只能從大方面說說，在本框架開發所需的范圍內來講述相關要用到的知識點，至于要更深入的去了解，請大家觀看其他大牛的博客或購買書籍來學習。
為了加快進度，會對目錄進行修改，將一些知識點合并或在后面使用的章節再進行描述。
謝謝大家的支持，如果您覺得本文對您有所幫助，請幫忙點擊支持或發表評論。
在開發的過程中，要編寫各種各樣的文檔，當然也有不少公司根本就沒有文檔。對于初學者，包括相當多有多年開發經驗的人，說起編寫文檔都會非常抗拒，一講到寫文檔很多人都是一個頭兩個大，不知道怎么編寫也懶的寫，大多都是能拖就拖，拖不了就草草應付，當然我當年也是其中的一份子o(∩_∩)o
為什么很多程序員會很抗拒寫文檔？
這個就不再詳細描述，你們問問自己就知道了。
本文的主要是想告訴初學者們，為什么我們要寫文檔，寫文檔對我們開發有什么幫助，以及對各種文檔有個大概的認識。
好處一：確認需求，減少程序修改工作量
很多朋友都碰到過拍腦袋的老板、客戶或領導（說的不好聽就是頭腦一熱，需求不過夜的人），而這些朋友真的是遍體鱗傷，給虐了一遍又一遍，而我也是屬于那個被虐的人，呵呵......
我以前有位同事，在一起共事時每個項目都要求他寫文檔，當時他一直都覺得很麻煩，后來換了公司后才真正體會到沒文檔的苦惱。他的老板是那種很有想法的人，經常會有新點子出來，所以在做項目時，一有新的想法就要求他實現 。而有的想法當時提出后過了一兩天就忘了，那么他就杯具了......有次他同我說，現在終于明白文檔的重要性了，沒有文檔的日子都不是人過的。
需求的不停變動對于程序員來說，是個永遠的痛/(╯^╰)/ ，當然我們也不能坐以待斃，而需求文檔就是我們最好的武器（對于那些所有項目都不需要文檔的公司不在本文的討論范圍之內）。具體的需求文檔編寫說明請留意后面的章節。
好處二：幫助我們熟悉項目
在編寫相關文檔時，其實就是幫助我們對項目的理解，理順一些算法思路。
沒有編寫文檔時，你經常會想當然，心里覺得已經很了解整個項目結構與需求了，要怎么實現也有了想法，而人的記憶是會遺忘的，等開發一段時間后，原來想要實現的功能可能就忘得一干二凈了。而在編寫文檔的時候，會幫我們認真的考慮整個需求，對一些要求也會詳細斟酌，從中發現很多我們沒有想到的問題，然后再深入的去考慮怎么解決這些問題，要用什么算法，會不會再引發更多的問題.....文檔完成后，整個項目其實就等于在你的大腦里面實現過一次了，在進入開發階段就會比較順風順水，開發效率也會很高效。
好處三：提高開發效率，防止出錯
記得好幾年前在一家手機群發、扣費公司上班，當時要開發一個功能，可以在服務器端根據需要控制手機扣費使用渠道、價格...的功能，在接到這個開發需求時，我并不是馬上編碼，而是花了四五天時間在整理需求，編寫對應的開發文檔與流程圖，由于有完善的開發文檔與流程圖（具體請看當時的流程設計圖），只花了一天時間就完成了主要的業務邏輯，一個2K多行的存儲過程（含注釋，后來不斷的添加新業務最后擴展到3K多行），又花了半天開發出手機端調用程序和服務器端調用接口，而最后測試只花了半天時間，修改了幾個小BUG就搞定可以上線了。上線后頂著經常瞬間幾K并發量壓力，一直運行到公司轉型，二年多時間都沒有出現過什么問題，為什么這么復雜的邏輯，但開發占用時間很短，測試上線后在大并發的壓力下運行都很正常呢？主要的功勞是做足了前期的需求分析與開發文檔編寫，如果沒有的話，嘿嘿......試過的人都知道，你懂的。只有真正了解項目需求，理順項目流程，并做了深入思考，那么很多常見的問題都可以迎刃而解。
好處四：控制項目進度
如果沒有文檔，開發一個新項目時所定下的開發周期絕大部分都是很有水份的，有多少能按時完成也是個未知數。
而有詳細的文檔說明、數據庫設計、流程圖、功能設計都出來后，這時有經驗的開發人員繪制甘特圖制定的項目開發進度就比較靠譜了。然后開發團隊根據開發計劃，控制好每天完成的功能進度，一般都能按時完成開發要求，就算有偏差也不會太離譜（除非中間需求變動或制定計劃的人經驗不足）。
好處五：為后期測試工作提供指引
有了完善的文檔，在進入測試階段時，就可以根據需求文檔與開發文檔對功能進行測試，編寫測試用例。如果沒有文檔，都不知道初始功能求要是什么，那只能測已完成的功能、UI等模塊了。
好處六：為二次開發與軟件維護提供支持
在上一文中已說過相關例子，沒有文檔資料、缺少注釋，而代碼又不規范的話，那就是一個大坑，一個很難填平的黑坑。
...... （其他幫助）
除了以上好處外，對于初學者來說，能編寫一份好文檔，并配合相應的成功作品，這將是你職業生涯最好的敲門磚，能提高你自身的價值和應聘成功機率。
不是任何時候都需要編寫規范的文檔 當然不是任何項目都需要編寫文檔的，對于小公司小項目，開發人員只有一兩個人的話，為了追求快速出產品，快速上線，特別是有一個好框架的情況下，沒有文檔也并不是大不了的事情。
不同公司有不同的文檔編寫要求，而格式也是大不相同。對于要求比較規范的大公司，這些文檔的編寫大都會嚴格的按軟件工程要求的格式來，當然這樣做的話沒有一定經驗，寫起來會比較吃力，花的時間也比較長，而當今的網絡社會是快魚吃慢魚的時代，對于中小公司或個人開發，如果花太多時間的話，那就得不償失了，所以還是根據具體情況而定，編寫的文檔格式與要求相應做出調整。
對于初學者文檔應該怎么編寫呢？使用什么模板或格式？
在一個項目從開始提出需求到實施結束，這個過程會涉及很多文檔的編寫，在編寫的過程中，對于初學者來說并不好把握，常常會不知道使用什么格式、排版，內容要怎么來寫。
一般來說通用的模板內容大都內容全面、詳細，比較復雜，初學者沒有經驗寫起來會比較吃力。所以編寫時可以使用通用模板進行模仿，但不用全部照搬。
實際上編寫文檔就像寫作文，只要條理清晰的講述出相關內容，突出重點，不要偏離該文檔主題就可以了。當然如果你能詳細的將5個W2H原則說明清楚，再配上相應的圖例（流程圖），那就更棒了。
5個W2H原則說明：1.WHY ——為什么？為什么要這么做？理由何在？原因是什么？2. WHAT——是什么？目的是什么？做什么工作？3. WHERE——何處？在哪里做？從哪里入手？4.WHEN——何時？什么時間完成？什么時機最適宜？5. WHO——誰？由誰來承擔？誰來完成？誰負責？6.HOW——怎么做？如何提高效率？如何實施？方法怎樣？7. HOW MUCH——多少？做到什么程度？需要多少時間？數量如何？質量水平如何？費用產出如何？ 不同文檔的主題是什么？
需求文檔主要是為了讓實施方了解軟件開發完成后要達到的效果，以及和需求方對軟件功能進行文檔確認。 概要設計（總體設計）文檔主要是為了和需求方進一步確認需求，以及軟件設計的功能是否設置合理。同時也作為后面詳細功能設計、數據庫設計以及其他相關設計的總體指導，了解開發過程中需要使用的基本算法，以及可能遇到的問題。也方便將詳細設計以及相關設計任務進行切分，分配給不同的負責人共同編寫，減少花費時間。 詳細設計文檔主要是將總體設計里所講述的內容進行細化，詳細描述所要實現的功能、算法以及流程圖。細化到每個頁面要放置什么按鈕、字段，列表中要顯示什么內容，頁面要實現什么功能，而實現這些功能可能要使用什么算法等。當寫完詳細設計后整個項目基本上就出來了。 數據庫設計是一個很重要的環節，因為好的設計會給整個系統帶好良好的性能，為開發過程中減少不必要的代碼，提高開發效率有著很重要的幫助。數據庫設計是根據詳細設計里所描述的內容轉換成開發中的數據表與字段。而在進行數據庫設計時，常常會發現很多之前沒有考慮到的問題，會有很多新的想法與需求，需要添加新的字段，這時在添加的時候必須進行反復斟酌，判斷是否是必須添加的，是否必須在第一期開發中實現？能否放在第二期開發？對開發時間有沒有影響？影響有多大？因為很多新的想法與擴展都不是必須的，很多想法也需求實現后都沒有真正使用到，這樣的話就浪費時間。我們必須要按計劃與需求來進行開發，而不是隨意的添加新的功能進來，這樣才能做好開發進度的把控工作。而添加后必須同步更新詳細設計文檔，補充新添加的字段或功能描述。 項目開發計劃（甘特圖）文檔，主要是將詳細設計里的每個功能，在實施時進行開發人員，以及開發先后順序安排，并確認所需時間，制定開發計劃。
單元測試文檔，主要是編寫各種測試用例，包括各種極限用例的提交以及返回結果的預期文檔，幫助測試人員以及開發人員完善功能設計。
部署文檔主要是將發布到生產環境的操作步驟以及注意事項進行詳細描述，方便相關管理人員能輕松的部署最終上線版本，出現問題時快速找出并解決問題。
除了上面所描述的文檔外，還有很多各種各樣的文檔，當然大部分都不是本系列所要涉及的內容，所以暫時就不再深入描述，如果有需要再開單章進行細說。
當然實現開發中并不可能很理想化，將上面提到的文檔或步驟來實施，而真正的可能是盡可能的壓縮你的文檔時間（甚至沒有文檔），壓縮你的開發時間，以便能快速產出上線，當然對于小型企業網站或軟件來說問題不是很大，而稍微大些的項目，在測試階段就會非常的頭痛了，各種沒有考慮到的BUG接踵而來，開始進行扯皮。所以說能規范的話盡量規范，有可能編寫文檔的話，盡量將文檔補齊，這樣會減少后期大量的工作，就算有問題進行扯皮的時候，起碼有文字性的記載。而對于那些必須的變動要求，那也能讓需求方知道你做了多少事情，用了多少工作量，而不是給他們感覺才改了這一點點需求，沒什么大不了的，因為需求方大部分人都不知道你碼代碼時所花費的工作量與付出。
相關文檔的詳細格式與內容，請留意后面的相應章節。
版權聲明： 本文由AllEmpty原創并發布于博客園，歡迎轉載，未經本人同意必須保留此段聲明，且在文章頁面明顯位置給出原文鏈接，否則保留追究法律責任的權利。如有問題，可以通過1654937@QQ.com 聯系我，非常感謝。
發表本編內容，只要主為了和大家共同學習共同進步，有興趣的朋友可以加加Q群：327360708 或Email給我（[email protected]），大家一起探討。
更多內容，敬請觀注博客：http://www.companysz.com/EmptyFS/
新聞熱點
疑難解答
