第11章 文檔管理

軟件項(xiàng)目開(kāi)發(fā)方法與管理第11章文檔管理711.1文檔管理概述11.1.1文檔管理的概念軟件文檔是與軟件研制、維護(hù)和使用有關(guān)的材料，是以人們可讀的形式表示的技術(shù)數(shù)據(jù)和信息。軟件文檔規(guī)定軟件設(shè)計(jì)細(xì)節(jié)、說(shuō)明軟件功能、描述軟件使用方法。軟件文檔和計(jì)算機(jī)程序一起構(gòu)成一個(gè)完成特定功能的軟件跟蹤項(xiàng)目。作為開(kāi)發(fā)組成員之間交流溝通的媒體；為維護(hù)工程師提供有關(guān)信息系統(tǒng)的資料和知識(shí)庫(kù)；為管理者提供項(xiàng)目計(jì)劃、預(yù)算、開(kāi)發(fā)進(jìn)度等各方面的信息；作為最終用戶手冊(cè)或管理員手冊(cè)，使用戶知道如何使用、維護(hù)與管理系統(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.開(kāi)發(fā)文檔描述軟件開(kāi)發(fā)過(guò)程（包括軟件需求、軟件設(shè)計(jì)、軟件測(cè)試、軟件質(zhì)量保證）的一類文檔，也包括軟件的詳細(xì)技術(shù)描述（如程序邏輯、程序間相互關(guān)系、數(shù)據(jù)格式和存儲(chǔ)等）。

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

數(shù)據(jù)要求說(shuō)明書詳細(xì)設(shè)計(jì)說(shuō)明書4可行性研究報(bào)告56

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

管理依據(jù)

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

質(zhì)量保證

培訓(xùn)與參考

軟件維護(hù)支持

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

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

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

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

若可能，訪問(wèn)典型用戶（為了做讀者分析和可用性測(cè)試）。711.4文檔編制過(guò)程11.4.2文檔計(jì)劃計(jì)劃一般包括以下方面的內(nèi)容：列出應(yīng)編制文檔的目錄；提示編制文檔參考的標(biāo)準(zhǔn)；指定文檔管理員；提供編制文檔所需要的條件；

明確保證文檔質(zhì)量的方法；繪制進(jìn)度表；明確文檔計(jì)劃及文檔的分發(fā)情況，訪問(wèn)典型用戶。711.4文檔編制過(guò)程11.4.3文檔編號(hào)應(yīng)按各單位規(guī)定的編號(hào)方法對(duì)軟件文檔進(jìn)行編號(hào)，以便于管理。參考結(jié)構(gòu)：XX

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

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

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

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

注釋說(shuō)明