作者：張保軍 文章轉自：http://www.soft6.com/tech/12/122043.html
文檔是軟件項目開發應用的一部分，存在於軟件項目的整個生命週期之中，沒有正式文檔的軟件項目開發，就不是規範標準的軟件項目。文檔Bug是軟件缺陷的一種表現形式，通常客戶並不知道文檔是否存在Bug，如果按照帶有缺陷的文檔進行安裝操作，同樣會造成不良的後果，甚至帶來損失，在實際工作中因文檔質量不高，造成軟件投產後出現系統宕機、賬務扎賬錯誤等生產問題時有發生。因此，文檔的編制和管理在軟件項目開發中佔有突出的地位和相當大的工作量，高質量、高效率地設計、編制、分發、管理和維護文檔，對於轉讓、變更、修正、擴充和使用文檔，對於提高軟件項目的質量和客戶滿意度有着重要的現實意義。
1.文檔的涵義
軟件項目中的文檔是用來記錄、描述、展示軟件項目開發過程中一系列信息的處理過程，通過書面或圖示的形式對軟件項目整體活動過程或結果進行描述、定義、規定、報告及認證。它描述和規定了軟件項目開發的每一個細節，使用軟件的操作命令及軟件產品投產以後，對產品使用過程中意見及產品缺陷、質量等方面的說明。
2.文檔的作用 本文轉自項目管理者聯盟
(1)提高了軟件項目開發過程的能見度。標準規範、齊全的文檔，詳細記錄了軟件項目開發過程中發生的事件，便於項目管理人員檢查、掌握軟件開發進度、開發質量以及各種資源的調配，是開發人員進行軟件開發的依據，也是項目成員協調工作的依據。
(2)提高了軟件項目的開發效率。項目成員用一定時間編制、整理軟件文檔，可以使開發人員對各個階段的工作都進行周密思考和理順、找出存在的問題，從而減少差錯，提高軟件項目質量。同時，通過對完成文檔的檢查，在項目開發早期發現軟件文檔的錯誤和不一致性，加以及時糾正，可以減少文檔Bug深入項目而導致的大問題的出現和爲糾正這些錯誤而付出的更大的成本。
(3)便於軟件項目成員之間的交流與合作。文檔是一種無聲的語言，它記錄了軟件項目開發過程中有關軟件開發、運行、維護和培訓等方面的信息，這些信息有利於管理人員、開發人員、操作人員、用戶之間的交流和合作，便於軟件項目能在規定的時間、費用內完成開發和投產應用。
(4)方便客戶選購軟件產品。描述清楚、完備的文檔便於客戶瞭解軟件的功能、性能等各項指標，爲客戶選購符合自己需要的軟件提供依據，是在客戶與軟件開發企業之間架起的一座橋樑。
(5)是做好軟件項目投產維護工作的保證。高質量的文檔可以幫助技術人員順利完成軟件的安裝，並及時排除軟件系統運行過程中出現的各種錯誤，可以幫助客戶知道在使用操作過程中出現的錯誤信息含義，及時處理出現的問題並順利完成工作。因此，高質量的文檔是軟件項目順利投產的保障。
(6)有利於操作人員正確操作，減少操作失誤。操作人員對產品的認識更多地是來自有關軟件產品的使用說明文檔，這些文檔可以提高操作人員正確、快速地爲客戶辦理業務的質量，做好產品的宣傳，發揮產品性能，爲客戶提供周到細緻的服務。
(7)有利於客戶正確操作自助設備。描述簡單、正確、清晰的文檔，便於客戶儘快地掌握ATM、POS、網上銀行、手機銀行及自助終端等各種自助設備的操作，方便客戶，增強客戶對金融產品的認知，提高自助設備的使用率和效益。
3.文檔的分類
(1)開發文檔：這類文檔在軟件項目開發過程中，體現了軟件開發人員前一階段工作的成果，同時又是後一階段工作的依據。這類文檔包括可行性研究報告、軟件項目開發計劃、軟件需求規格說明、系統規格說明書、軟件功能說明書和數據字典等。
(2)管理文檔：這類文檔在軟件項目開發過程中，由軟件開發人員制定的需提交管理部門的一些工作計劃、工作方案和工作報告。通過閱讀這些文檔，管理人員能夠了解軟件項目開發活動安排、進度、資源使用等情況。這類文檔包括項目開發計劃、測試計劃、測試方案、開發進度報告和項目總結報告等。
(3)用戶文檔：這類文檔是軟件開發人員爲使用該軟件的網點經辦人員準備的有關該軟件產品使用、操作的資料，主要是操作手冊及新功能介紹方面的文檔。
(4)投產文檔：這類文檔主要是軟件開發人員對數據中心、分行科技人員準備的有關投產說明、版本安裝、軟件測試等方面的資料。
(5)記錄文檔：與客戶交流往來的記錄、軟件項目開發過程中各種會議、跟蹤記錄、審查記錄、產品投產記錄和問題跟蹤解決記錄等。
(6)反饋文檔：這類文檔主要是軟件產品在推廣使用以後，客戶對產品使用過程中意見及產品缺陷、質量等方面的信息反饋。
4.文檔常見問題
(1)文檔編寫不夠規範。主要表現在軟件項目實施過程中，沒有對每一個階段的文檔進行整理，分層次管理，各類文檔資料缺少一個可以參照的樣本，更多的是在以前他人寫好的基礎上，對內容進行修改一下就算完成任務。
(2)文檔內容描寫不夠完善。在編寫各種文檔過程中，雖然大家都按事先規定的模式進行了編寫，但編寫的內容經常不夠完善，夾雜着一些舊的東西沒有及時更新。特別是一些參數表、用戶手冊等一些由數據中心、分行使用的文檔，由於一時的疏漏，造成軟件項目投產失敗、投產後造成系統宕機、出現賬務差錯、客戶按照你的操作說明不能得到正確的結果等現象的發生。
(3)對文檔評審不夠，使用效果不理想。按照軟件工程的要求，在軟件項目的開發過程中從設計到投產，要編寫一系列的文檔，編寫這些文檔是必須的，但經常會出現這樣的現象，在軟件開發企業，某職能部門負責人員自行制定了文檔模板後，就通知各部門進行使用，結果大家反映效果不好，分析原因是沒有在編寫時很好地依據企業自身的現狀，從實際出發徵求大家的意見，對投入使用的文檔沒有組織相關人員進行評審。
(4)重視文檔的形式，實用性不強。在實際的軟件開發過程中，要求編制的文檔非常多，但編制人員沒有時間去關心它們的用途，也不知道哪些部門使用，更多的是在規定的時間內完成任務，以免影響考覈成績，這樣一來一些不實用的、重複的文檔編制工作，佔用了開發人員有效的設計開發時間，影響了項目的整體進度。因此，軟件文檔的制定要實用，減少繁文縟節的文字工作。
(5)文檔沒有統一入庫管理。隨着系統的不斷優化、升級，新需求的不斷產生，各種文檔越來越多，沒有建立一個文檔資料信息庫，統一存放軟件項目不同時期的各種文檔，零散存在的文檔，造成查詢、統計一個軟件項目完整的文檔信息時非常困難。
(6)對文檔的編制重視不夠。大家常常把文檔作爲軟件產品的附件，對待文檔資料沒有像對待程序代碼一樣關注和投入，文檔中普遍存在錯別字、語句涵義表達不清楚，口語化濃厚，引用的圖表不夠準確，主題表達不夠清晰等現象。
(7)對文檔的測試不足。通常測試主要是針對軟件項目功能的測試，對該軟件項目的文檔測試則很少進行。通常用戶把文檔當成了軟件產品的一部分，在軟件產品安裝使用過程中，不正確的提示信息把客戶引入歧途，不但得不到預期的結果，還會產生錯誤，給用戶帶來麻煩。
5.文檔編制要求
(1)標準化：從需求分析開始到投產應用所有涉及的每一種文檔，都要給出一個可以執行的模板，所有完成的文檔從裏到外都要非常工整，具有專業水準，符合ISO9000及CMM質量標準要求。
(2)易用性：編制的各種軟件文檔，要便於不同的崗位人員進行閱讀、理解、學習和使用。
(3)簡潔性：要求軟件項目中需要編寫的文檔內容突出主題，只反映要描述的問題，不包含其他不必要的東西，語言表達簡明扼要，一清二楚，如有可能，可以配以適當的圖表，以增強其清晰性。
(4)針對性：文檔要按不同的類型、面對不同的對象，實行差異化編制，根據實際需要進行編寫，也就是說文檔編寫目的要明確，因需而變。例如管理文檔主要面向管理人員，用戶文檔主要面向用戶，這兩類文檔不應像開發文檔(面向開發人員)那樣過多使用軟件的專用術語。
(5)一致性：文檔的行文應當十分確切，對於同一現象的描寫，不能出現多義性的描述，同一項目中幾個文檔描述的內容應當是一致的，相互之間沒有矛盾。
(6)完整性：任何一個文檔都應當是完整的、獨立的，沒有遺漏和丟失的內容。也就是說每一種文檔在設計時可以包含必要的圖形、模型、敘述、表、索引、附錄和參考文獻，列舉的這些內容都是完整的。同一軟件項目涉及的幾個文檔之間可能存在部分內容相同，這種重複是必要的，不要在文檔中出現“見XX文檔XX章節”的現象。
(7)靈活性：在實際操作中要針對軟件項目規模和複雜程度的不同，對現行的文檔進行修正，決定編制的文檔種類。可以依據自身軟件開發情況，制定一個對文檔編制的規定，用列表的形式列出在項目什麼條件下，應該形成哪些文檔，這些文檔的詳細程度。
(8)可追溯性：在軟件項目的開發過程中，各個階段編制的文檔不是孤立的，而是與各個階段完成的工作有密切的關係，隨着項目開發工作的進展，具有一定的繼承關係，體現出了可追溯的特性，如軟件需求會在設計說明書、測試設計方案及用戶手冊中有所體現。
(9)設定優先級：在軟件項目衆多的文檔中，其中一些文檔必定是關鍵文檔，起到非常重要的作用。對於這類文檔要設定優先級別特別關注，不能有任何的錯誤存在，對於一些關鍵的地方要特別標記，特別說明。
6.文檔的審覈
審覈就是檢查編寫的項目文檔是否齊全有無遺漏，是否符合文檔的規範要求，內容描寫是否正確緊扣主題，列出的圖表信息是否準確，以確保文檔的質量。審覈要花費一定的人力和時間，但效果是顯著的。通過對文檔進行全面的審覈、充分的測試，有效地發現文檔中存在的問題，如遺漏的需求、多餘的功能設計內容、不切實際的測試計劃、不可行的測試方案、不充分的測試案例和不合格的操作手冊等，提前發現問題、改正問題。這樣比客戶使用軟件時遇到麻煩或軟件項目推廣應用中出現問題時再向項目開發人員尋求支持更有效，且能提高客戶的滿意度，減少出錯返工的成本和時間。
7.使用工具管理文檔
對於一個大型的軟件項目系統，從形成概念開始，經過設計、開發、推廣使用和不斷增補修訂，直到最後被淘汰的整個項目生命週期中都要編寫大量的文檔。而文檔編寫的內容是在不斷變化的，有的是連續的，承前啓後的，有的是新增加的，也有的是廢除的，如何管理好這些文檔資料，爲大家提供最新的信息，便於日常的調用查詢，便於信息的利用，是發揮文檔作用的重要一環，否則就是佔用空間的垃圾。這就需要設計開發一個統一的軟件文檔管理工具，分門別類統一存放管理各種文檔資料，建立軟件文檔資料信息庫，供大家隨時查詢調用。
總之，文檔在軟件項目的開發過程中起到了關鍵的作用，從某種意義上來說，文檔是軟件項目開發規範的體現和指南，按照規範要求編制一整套文檔的過程，就是按照開發規範完成一個軟件項目開發的過程。高質量的文檔可以提高軟件項目的質量，有助於程序員編制程序，有助於管理人員監督和管理軟件的開發，有助於用戶更好地安裝和使用軟件系統，有助於維護人員進行有效的修改和擴充。所以，在軟件項目的開發過程中，要充分做好軟件文檔的編制和管理工作。