軟件項目開發(fā)中文檔的編制和管理

1、 軟件項目開發(fā)中文檔的編制和管理文檔是軟件項目開發(fā)應(yīng)用的一部分，存在于軟件項目的整個生命周期之中，沒有正式文檔的軟件項目開發(fā)，就不是規(guī)范標(biāo)準(zhǔn)的軟件項目。文檔Bug是軟件缺陷的一種表現(xiàn)形式，通?？蛻舨⒉恢牢臋n是否存在Bug，如果按照帶有缺陷的文檔進(jìn)行安裝操作，同樣會造成不良的后果，甚至帶來損失，在實際工作中因文檔質(zhì)量不高，造成軟件投產(chǎn)后出現(xiàn)系統(tǒng)宕機(jī)、賬務(wù)扎賬錯誤等生產(chǎn)問題時有發(fā)生。因此，文檔的編制和管理在軟件項目開發(fā)中占有突出的地位和相當(dāng)大的工作量，高質(zhì)量、高效率地設(shè)計、編制、分發(fā)、管理和維護(hù)文檔，對于轉(zhuǎn)讓、變更、修正、擴(kuò)充和使用文檔，對于提高軟件項目的質(zhì)量和客戶滿意度有著重要的現(xiàn)實意義。 1

2、.文檔的涵義 軟件項目中的文檔是用來記錄、描述、展示軟件項目開發(fā)過程中一系列信息的處理過程，通過書面或圖示的形式對軟件項目整體活動過程或結(jié)果進(jìn)行描述、定義、規(guī)定、報告及認(rèn)證。它描述和規(guī)定了軟件項目開發(fā)的每一個細(xì)節(jié)，使用軟件的操作命令及軟件產(chǎn)品投產(chǎn)以后，對產(chǎn)品使用過程中意見及產(chǎn)品缺陷、質(zhì)量等方面的說明。 2.文檔的作用 （1）提高了軟件項目開發(fā)過程的能見度。標(biāo)準(zhǔn)規(guī)范、齊全的文檔，詳細(xì)記錄了軟件項目開發(fā)過程中發(fā)生的事件，便于項目管理人員檢查、掌握軟件開發(fā)進(jìn)度、開發(fā)質(zhì)量以及各種資源的調(diào)配，是開發(fā)人員進(jìn)行軟件開發(fā)的依據(jù)，也是項目成員協(xié)調(diào)工作的依據(jù)。 （2）提高了軟件項目的開發(fā)效率。項目成員用一定時間編

3、制、整理軟件文檔，可以使開發(fā)人員對各個階段的工作都進(jìn)行周密思考和理順、找出存在的問題，從而減少差錯，提高軟件項目質(zhì)量。同時，通過對完成文檔的檢查，在項目開發(fā)早期發(fā)現(xiàn)軟件文檔的錯誤和不一致性，加以及時糾正，可以減少文檔Bug深入項目而導(dǎo)致的大問題的出現(xiàn)和為糾正這些錯誤而付出的更大的成本。 （3）便于軟件項目成員之間的交流與合作。文檔是一種無聲的語言，它記錄了軟件項目開發(fā)過程中有關(guān)軟件開發(fā)、運行、維護(hù)和培訓(xùn)等方面的信息，這些信息有利于管理人員、開發(fā)人員、操作人員、用戶之間的交流和合作，便于軟件項目能在規(guī)定的時間、費用內(nèi)完成開發(fā)和投產(chǎn)應(yīng)用。 （4）方便客戶選購軟件產(chǎn)品。描述清楚、完備的文檔便于客戶了

4、解軟件的功能、性能等各項指標(biāo)，為客戶選購符合自己需要的軟件提供依據(jù)，是在客戶與軟件開發(fā)企業(yè)之間架起的一座橋梁。（5）是做好軟件項目投產(chǎn)維護(hù)工作的保證。高質(zhì)量的文檔可以幫助技術(shù)人員順利完成軟件的安裝，并及時排除軟件系統(tǒng)運行過程中出現(xiàn)的各種錯誤，可以幫助客戶知道在使用操作過程中出現(xiàn)的錯誤信息含義，及時處理出現(xiàn)的問題并順利完成工作。因此，高質(zhì)量的文檔是軟件項目順利投產(chǎn)的保障。 （6）有利于操作人員正確操作，減少操作失誤。操作人員對產(chǎn)品的認(rèn)識更多地是來自有關(guān)軟件產(chǎn)品的使用說明文檔，這些文檔可以提高操作人員正確、快速地為客戶辦理業(yè)務(wù)的質(zhì)量，做好產(chǎn)品的宣傳，發(fā)揮產(chǎn)品性能，為客戶提供周到細(xì)致的服務(wù)。（7）有

5、利于客戶正確操作自助設(shè)備。描述簡單、正確、清晰的文檔，便于客戶盡快地掌握ATM、POS、網(wǎng)上銀行、手機(jī)銀行及自助終端等各種自助設(shè)備的操作，方便客戶，增強(qiáng)客戶對金融產(chǎn)品的認(rèn)知，提高自助設(shè)備的使用率和效益。 3.文檔的分類 （1）開發(fā)文檔：這類文檔在軟件項目開發(fā)過程中，體現(xiàn)了軟件開發(fā)人員前一階段工作的成果，同時又是后一階段工作的依據(jù)。這類文檔包括可行性研究報告、軟件項目開發(fā)計劃、軟件需求規(guī)格說明、系統(tǒng)規(guī)格說明書、軟件功能說明書和數(shù)據(jù)字典等。 （2）管理文檔：這類文檔在軟件項目開發(fā)過程中，由軟件開發(fā)人員制定的需提交管理部門的一些工作計劃、工作方案和工作報告。通過閱讀這些文檔，管理人員能夠了解軟件項目

6、開發(fā)活動安排、進(jìn)度、資源使用等情況。這類文檔包括項目開發(fā)計劃、測試計劃、測試方案、開發(fā)進(jìn)度報告和項目總結(jié)報告等。 （3）用戶文檔：這類文檔是軟件開發(fā)人員為使用該軟件的網(wǎng)點經(jīng)辦人員準(zhǔn)備的有關(guān)該軟件產(chǎn)品使用、操作的資料，主要是操作手冊及新功能介紹方面的文檔。4）投產(chǎn)文檔：這類文檔主要是軟件開發(fā)人員對數(shù)據(jù)中心、分行科技人員準(zhǔn)備的有關(guān)投產(chǎn)說明、版本安裝、軟件測試等方面的資料。 （5）記錄文檔：與客戶交流往來的記錄、軟件項目開發(fā)過程中各種會議、跟蹤記錄、審查記錄、產(chǎn)品投產(chǎn)記錄和問題跟蹤解決記錄等。 （6）反饋文檔：這類文檔主要是軟件產(chǎn)品在推廣使用以后，客戶對產(chǎn)品使用過程中意見及產(chǎn)品缺陷、質(zhì)量等方面的信息

7、反饋。 4.文檔常見問題（1）文檔編寫不夠規(guī)范。主要表現(xiàn)在軟件項目實施過程中，沒有對每一個階段的文檔進(jìn)行整理，分層次管理，各類文檔資料缺少一個可以參照的樣本，更多的是在以前他人寫好的基礎(chǔ)上，對內(nèi)容進(jìn)行修改一下就算完成任務(wù)。 （2）文檔內(nèi)容描寫不夠完善。在編寫各種文檔過程中，雖然大家都按事先規(guī)定的模式進(jìn)行了編寫，但編寫的內(nèi)容經(jīng)常不夠完善，夾雜著一些舊的東西沒有及時更新。特別是一些參數(shù)表、用戶手冊等一些由數(shù)據(jù)中心、分行使用的文檔，由于一時的疏漏，造成軟件項目投產(chǎn)失敗、投產(chǎn)后造成系統(tǒng)宕機(jī)、出現(xiàn)賬務(wù)差錯、客戶按照你的操作說明不能得到正確的結(jié)果等現(xiàn)象的發(fā)生。 （3）對文檔評審不夠，使用效果不理想。按照軟

8、件工程的要求，在軟件項目的開發(fā)過程中從設(shè)計到投產(chǎn)，要編寫一系列的文檔，編寫這些文檔是必須的，但經(jīng)常會出現(xiàn)這樣的現(xiàn)象，在軟件開發(fā)企業(yè)，某職能部門負(fù)責(zé)人員自行制定了文檔模板后，就通知各部門進(jìn)行使用，結(jié)果大家反映效果不好，分析原因是沒有在編寫時很好地依據(jù)企業(yè)自身的現(xiàn)狀，從實際出發(fā)征求大家的意見，對投入使用的文檔沒有組織相關(guān)人員進(jìn)行評審。 （4）重視文檔的形式，實用性不強(qiáng)。在實際的軟件開發(fā)過程中，要求編制的文檔非常多，但編制人員沒有時間去關(guān)心它們的用途，也不知道哪些部門使用，更多的是在規(guī)定的時間內(nèi)完成任務(wù)，以免影響考核成績，這樣一來一些不實用的、重復(fù)的文檔編制工作，占用了開發(fā)人員有效的設(shè)計開發(fā)時間，影

9、響了項目的整體進(jìn)度。因此，軟件文檔的制定要實用，減少繁文縟節(jié)的文字工作。（5）文檔沒有統(tǒng)一入庫管理。隨著系統(tǒng)的不斷優(yōu)化、升級，新需求的不斷產(chǎn)生，各種文檔越來越多，沒有建立一個文檔資料信息庫，統(tǒng)一存放軟件項目不同時期的各種文檔，零散存在的文檔，造成查詢、統(tǒng)計一個軟件項目完整的文檔信息時非常困難。 （6）對文檔的編制重視不夠。大家常常把文檔作為軟件產(chǎn)品的附件，對待文檔資料沒有像對待程序代碼一樣關(guān)注和投入，文檔中普遍存在錯別字、語句涵義表達(dá)不清楚，口語化濃厚，引用的圖表不夠準(zhǔn)確，主題表達(dá)不夠清晰等現(xiàn)象。（7）對文檔的測試不足。通常測試主要是針對軟件項目功能的測試，對該軟件項目的文檔測試則很少進(jìn)行。通

10、常用戶把文檔當(dāng)成了軟件產(chǎn)品的一部分，在軟件產(chǎn)品安裝使用過程中，不正確的提示信息把客戶引入歧途，不但得不到預(yù)期的結(jié)果，還會產(chǎn)生錯誤，給用戶帶來麻煩。 5.文檔編制要求 （1）標(biāo)準(zhǔn)化：從需求分析開始到投產(chǎn)應(yīng)用所有涉及的每一種文檔，都要給出一個可以執(zhí)行的模板，所有完成的文檔從里到外都要非常工整，具有專業(yè)水準(zhǔn)，符合ISO9000及CMM質(zhì)量標(biāo)準(zhǔn)要求。 （2）易用性：編制的各種軟件文檔，要便于不同的崗位人員進(jìn)行閱讀、理解、學(xué)習(xí)和使用。 （3）簡潔性：要求軟件項目中需要編寫的文檔內(nèi)容突出主題，只反映要描述的問題，不包含其他不必要的東西，語言表達(dá)簡明扼要，一清二楚，如有可能，可以配以適當(dāng)?shù)膱D表，以增強(qiáng)其清晰

11、性。（4）針對性：文檔要按不同的類型、面對不同的對象，實行差異化編制，根據(jù)實際需要進(jìn)行編寫，也就是說文檔編寫目的要明確，因需而變。例如管理文檔主要面向管理人員，用戶文檔主要面向用戶，這兩類文檔不應(yīng)像開發(fā)文檔(面向開發(fā)人員)那樣過多使用軟件的專用術(shù)語。 （5）一致性：文檔的行文應(yīng)當(dāng)十分確切，對于同一現(xiàn)象的描寫，不能出現(xiàn)多義性的描述，同一項目中幾個文檔描述的內(nèi)容應(yīng)當(dāng)是一致的，相互之間沒有矛盾。 （6）完整性：任何一個文檔都應(yīng)當(dāng)是完整的、獨立的，沒有遺漏和丟失的內(nèi)容。也就是說每一種文檔在設(shè)計時可以包含必要的圖形、模型、敘述、表、索引、附錄和參考文獻(xiàn)，列舉的這些內(nèi)容都是完整的。同一軟件項目涉及的幾個文

12、檔之間可能存在部分內(nèi)容相同，這種重復(fù)是必要的，不要在文檔中出現(xiàn)“見XX文檔XX章節(jié)”的現(xiàn)象。（7）靈活性：在實際操作中要針對軟件項目規(guī)模和復(fù)雜程度的不同，對現(xiàn)行的文檔進(jìn)行修正，決定編制的文檔種類。可以依據(jù)自身軟件開發(fā)情況，制定一個對文檔編制的規(guī)定，用列表的形式列出在項目什么條件下，應(yīng)該形成哪些文檔，這些文檔的詳細(xì)程度。 （8）可追溯性：在軟件項目的開發(fā)過程中，各個階段編制的文檔不是孤立的，而是與各個階段完成的工作有密切的關(guān)系，隨著項目開發(fā)工作的進(jìn)展，具有一定的繼承關(guān)系，體現(xiàn)出了可追溯的特性，如軟件需求會在設(shè)計說明書、測試設(shè)計方案及用戶手冊中有所體現(xiàn)。 （9）設(shè)定優(yōu)先級：在軟件項目眾多的文檔中，

13、其中一些文檔必定是關(guān)鍵文檔，起到非常重要的作用。對于這類文檔要設(shè)定優(yōu)先級別特別關(guān)注，不能有任何的錯誤存在，對于一些關(guān)鍵的地方要特別標(biāo)記，特別說明。6.文檔的審核審核就是檢查編寫的項目文檔是否齊全有無遺漏，是否符合文檔的規(guī)范要求，內(nèi)容描寫是否正確緊扣主題，列出的圖表信息是否準(zhǔn)確，以確保文檔的質(zhì)量。審核要花費一定的人力和時間，但效果是顯著的。通過對文檔進(jìn)行全面的審核、充分的測試，有效地發(fā)現(xiàn)文檔中存在的問題，如遺漏的需求、多余的功能設(shè)計內(nèi)容、不切實際的測試計劃、不可行的測試方案、不充分的測試案例和不合格的操作手冊等，提前發(fā)現(xiàn)問題、改正問題。這樣比客戶使用軟件時遇到麻煩或軟件項目推廣應(yīng)用中出現(xiàn)問題時再向項目開發(fā)人員尋求支持更有效，且能提高客戶的滿意度，減少出錯返工的成本和時間。 7.使用工具管理文檔 對于一個大型的軟件項目系統(tǒng)，從形成概念開始，經(jīng)過設(shè)計、開發(fā)、推廣使用和不斷增補(bǔ)修訂，直到最后被淘汰的整個項目生命周期中都要編寫大量的文檔。而文檔編寫的內(nèi)容是在不斷變化的，有的是連續(xù)的，承前啟后的，有的是新增加的，也有的是廢除的，如何管理好這些文檔資料，為大家提供最新的信息，便于日常的調(diào)用查詢，便于信息的利用，是發(fā)揮文檔作用的重要一環(huán)，否則就是占用空間的垃圾。這就需要設(shè)計開發(fā)一個統(tǒng)一的軟件文檔管理工具，分門別類統(tǒng)一存放管理各種文檔資料，建立軟件文檔資料信息