第11章 文檔管理

軟件項目開發(fā)方法與管理第11章文檔管理711.1文檔管理概述11.1.1文檔管理的概念軟件文檔是與軟件研制、維護和使用有關的材料，是以人們可讀的形式表示的技術數(shù)據(jù)和信息。軟件文檔規(guī)定軟件設計細節(jié)、說明軟件功能、描述軟件使用方法。軟件文檔和計算機程序一起構成一個完成特定功能的軟件跟蹤項目。作為開發(fā)組成員之間交流溝通的媒體；為維護工程師提供有關信息系統(tǒng)的資料和知識庫；為管理者提供項目計劃、預算、開發(fā)進度等各方面的信息；作為最終用戶手冊或管理員手冊，使用戶知道如何使用、維護與管理系統(tǒng)

。711.1文檔管理概述11.1.2文檔管理工具WISS文檔協(xié)同系統(tǒng)；DirectoryOpusforx64；

文管王文件管理系統(tǒng)；WordTools文檔批量處理工具。711.1文檔管理概述11.1.3文檔與軟件規(guī)模711.2文檔的分類與作用11.2.1文檔分類1.開發(fā)文檔描述軟件開發(fā)過程（包括軟件需求、軟件設計、軟件測試、軟件質量保證）的一類文檔，也包括軟件的詳細技術描述（如程序邏輯、程序間相互關系、數(shù)據(jù)格式和存儲等）。

軟件需求規(guī)格說明書12

數(shù)據(jù)要求說明書詳細設計說明書4可行性研究報告56

項目開發(fā)計劃概要設計說明書3711.2文檔的分類與作用11.2.1文檔分類2.產(chǎn)品文檔是描述開發(fā)過程的產(chǎn)物，規(guī)定關于軟件產(chǎn)品的使用、維護、增強、轉換和傳輸?shù)刃畔?，供用戶、運行者和維護人員使用。培訓手冊12參考手冊軟件支持手冊4產(chǎn)品手冊56信息廣告用戶指南3711.2文檔的分類與作用11.2.1文檔分類3.管理文檔從管理角度記錄項目管理信息，這些信息包括：開發(fā)過程每個階段的進度和進度變更記錄、軟件變更情況記錄、相對于開發(fā)的判定記錄及職責定義。項目開發(fā)計劃12測試計劃測試報告4開發(fā)進度月報56項目開發(fā)總結配置管理計劃3711.2文檔的分類與作用11.2.2文檔作用

管理依據(jù)

任務之間聯(lián)系的憑證

質量保證

培訓與參考

軟件維護支持

歷史檔案711.3文檔編制要求1.基本要求制定計劃，標識在軟件產(chǎn)品生命周期期間產(chǎn)生的文檔；每一種標識的文檔應根據(jù)適用的文檔編寫標準進行編寫；確認文檔輸入數(shù)據(jù)的來源?？梢允褂米詣踊奈臋n編寫工具；按照文檔編寫標準的格式、技術內容和表達方式要求，評審和編輯產(chǎn)生的文檔；按照計劃產(chǎn)生和提供文檔。文檔的產(chǎn)生和發(fā)布可以使用紙張、電子媒體或其它媒體；按照配置管理過程進行控制；在修改文檔時需要執(zhí)行的任務應按照維護過程進行。711.3文檔編制要求2.管理要求管理者嚴格要求軟件開發(fā)人員和編制組完成文檔編制，并且在策略、標準、規(guī)程、資源分配和編制計劃方面給予支持。管理者對文檔工作的責任；管理者對文檔工作的支持；管理者的主要職責（6項）；項目管理者在項目開發(fā)前應決定的事項（7項）。711.4文檔編制過程711.4文檔編制過程開發(fā)文檔活動應按照材料準備、文檔計劃、文檔編制、文檔編號、文檔評審、文檔簽署、文檔歸檔、文檔保管和文檔維護的邏輯順序進行。711.4文檔編制過程11.4.1材料準備

所有有關的規(guī)格說明、記錄格式、屏幕和報告布局、CASE工具輸出以及文檔準備所需要的任何其它信息；

若可用，軟件的操作副本；

軟件分析員和程序員，能及時和確切地解答由文檔開發(fā)人員提出的問題；

若可能，訪問典型用戶（為了做讀者分析和可用性測試）。711.4文檔編制過程11.4.2文檔計劃計劃一般包括以下方面的內容：列出應編制文檔的目錄；提示編制文檔參考的標準；指定文檔管理員；提供編制文檔所需要的條件；

明確保證文檔質量的方法；繪制進度表；明確文檔計劃及文檔的分發(fā)情況，訪問典型用戶。711.4文檔編制過程11.4.3文檔編號應按各單位規(guī)定的編號方法對軟件文檔進行編號，以便于管理。參考結構：XX

Y.YYYZZZWW-M單位代號（XX）：某單位的編號；十進分類特征標記（Y.YYY）：按產(chǎn)品的技術特征給出的標記；

登記順序號（ZZZ）：由各單位標準化部門統(tǒng)一給定；文檔簡號（WW）：表示文檔的名稱，可按表11.1縮寫簡號；

媒體代號（M）：為區(qū)分源程序駐留的不同載體而給定的代號如表11.2所示。711.4文檔編制過程711.4文檔編制過程11.4.4文檔評審評審通常采用評審會的方式進行，步驟如下：由軟件開發(fā)單位負責人、用戶代表、開發(fā)小組成員、科技管理人員和標準化人員等組成評審小組，必要時還可邀請外單位的專家參加；開會前，由開發(fā)單位負責人確定評審的具體內容，并將評審材料發(fā)給評審小組成員，做好評審準備；由開發(fā)單位負責人主持評審會，根據(jù)文檔編制者對文檔的說明和評審條目，由評審小組成員進行評議、評審，評審結束應做出評審結論，評審小組成員應在評審結論上簽字。711.4文檔編制過程11.4.4文檔評審711.4文檔編制過程11.4.5文檔簽署各簽署者的技術責任如下：“編寫”簽署者，正確性、合理性、繼承性、可靠性、完整性、一致性負責；“校對”簽署者，與“編寫”簽署者負同等責任；“審核”簽署者，設計方案選擇的正確性、合理性，是否貫徹總體設計意圖，設計結果或結論是否正確、全面，圖例、術語、符號、公式、單位等是否貫徹標準和有關規(guī)定；“會簽”簽署者，正確性、合理性、完整性、協(xié)調性負責；“標準化”簽署者，編寫者是否貫徹先行標準和有關規(guī)章制度，軟件文檔的完整性和簽署是否完整正確；“批準”簽署者，功能、性能指標是否達到技術要求；軟件文檔的正確性、合理性和協(xié)調性；軟件文檔的完整性及設計質量；軟件文檔是否貫徹現(xiàn)行標準及有關規(guī)章制度。711.4文檔編制過程11.4.6文檔歸檔應將通過評審和簽署的軟件文檔及時歸檔。歸檔的文檔應包括整個軟件生命周期內形成的全部文檔。文檔歸檔應滿足如下條件：歸檔的文檔應是經(jīng)過鑒定或評審的；

文檔應簽署完整、成套、格式統(tǒng)一、字跡工整；印制本、打印本以及各種報告應裝訂成冊，并按規(guī)定進行編號和簽署。軟件文檔應在軟件開發(fā)過程每個階段結束后及時歸檔。711.4文檔編制過程11.4.7文檔保管通常應在不同地點建立設施來保存重要文檔副本；如果文檔是聯(lián)機開發(fā)的，則應將它存儲到磁帶或磁盤上，以便能夠迅速將這些文檔轉換成可用的形式；文檔保管包括登記、保存、借閱和修改等四項工作；文檔保管應按國家和上級主管部門的要求，以及各單位的規(guī)章制度規(guī)定執(zhí)行。711.4文檔編制過程11.4.8文檔維護軟件產(chǎn)品完成后，確定軟件維護人員；軟件運行過程中，記錄從用戶或其它途徑反饋回來的軟件質量信息；在分析整理后，按照GB/T8567的要求填寫“問題報告單”；根據(jù)“問題報告單”中提出的要求，填寫“修改申請報告”；根據(jù)申請批準的“修改申請報告”，對程序進行修改和測試；測試通過后，填寫“軟件修改報告”，并修改相應的文檔和媒體；將“軟件修改報告”和修改后的文檔送校對、審核、會簽、標準化和批準等有關負責人審閱和簽署；修改后的文檔、媒體和“軟件修改報告”送交檔案管理部門存檔；軟件維護人員匯總并整理修改的情況，編寫“軟件維護通報”。711.5文檔編制11.5.1編制策略文檔需要覆蓋整個軟件生命周期文檔應是可管理的文檔應適合于其讀者文檔作用應貫穿軟件整個開發(fā)過程文檔標準應被標識和使用應規(guī)定支持工具711.5文檔編制11.5.2文檔標準過程標準產(chǎn)品標準過程標準定義了書寫文檔的方法。這些通用方法規(guī)定了書寫文檔時要采用的軟件工具，同時也定義了為確保高質量文檔的質量確保程序。產(chǎn)品標準適用于在軟件開發(fā)過程中所有產(chǎn)生的文檔。文檔應該有一個統(tǒng)一的外觀，并且同一種類的文檔應該有統(tǒng)一的結構。交互標準在軟件項目開發(fā)過程中，軟件工程師之間的交流途徑更多采用電子化方式而不是紙質文件，文檔交互標準就變得越來越重要。711.5文檔編制11.5.3質量等級最低限度文檔（1極文檔）適合開發(fā)工作量低于一個人月的開發(fā)者自用程序。應包含程序清單、開發(fā)記錄、測試數(shù)據(jù)和程序簡介；內部文檔（2極文檔）用于在精心研究后被認為似乎沒有與其他用戶共享資源的專用程序。除1級文檔提供的信息外，還包括程序清單內足夠的注釋；工作文檔（3極文檔）適合于由同一單位內若干人聯(lián)合開發(fā)的程序，或可被其它單位使用的程序；最低限度文檔（1極文檔）適合要正式發(fā)行可供普遍使用的軟件產(chǎn)品。關鍵性程序或具有重復管理應用程序需要4級文檔。4級文檔遵守GB8567的有關規(guī)定。711.5文檔編制11.5.4質量要求針對性12精確性重復性5靈活性（見下頁）67可追溯性及時性3完整性4711.5文檔編制11.5.4質量要求靈活性包括：應編制的文檔種類；文檔的詳細程度；文檔擴展；章、條的擴張與縮并；程序設計的表現(xiàn)形式；文檔的表現(xiàn)形式；文檔的其它種類。71.5文檔編制1.5.5書寫風格文檔層次12

注釋說明