軟件文檔管理指南

PAGE4軟件文檔管理指南1范圍本標準為那些對軟件或基于軟件的產(chǎn)品的開發(fā)負有職責(zé)的管理者提供軟件文檔的管理指南。本標準的目的在于協(xié)助管理者在他們的機構(gòu)中產(chǎn)生有效的文檔。本標準涉及策略、標準、規(guī)程、資源和計劃，管理者必須關(guān)注這些內(nèi)容，以便有效地管理軟件文檔。本標準期望應(yīng)用于各種類型的軟件，從簡單的程序到復(fù)雜的軟件系統(tǒng)。并期望覆蓋各種類型的軟件文檔，作用于軟件生存期的各個階段。不論項目的大小，軟件文檔管理的原則是一致的。對于小項目，可以不采用本標準中規(guī)定的有關(guān)細節(jié)。管理者可剪裁這些內(nèi)容以滿足他們的特殊需要。本標準是針對文檔編制管理而提出的，不涉及軟件文檔的內(nèi)容和編排。2引用標準下列標準所包含的條文，通過在本標準中引用而構(gòu)成為本標準的條文。本標準出版時，所示版本均為有效，所有標準都會被修訂，使用本標準的各方應(yīng)探討使用下列標準最新版本的可能性。GB8566-88計算機軟件開發(fā)規(guī)范GB8567-88計算機軟件產(chǎn)品開發(fā)文件編制指南GB/T11457-1995軟件工程術(shù)語3定義本標準采用下列定義，其他定義見GB/T11457。3.1文檔document一種數(shù)據(jù)媒體和其上所記錄的數(shù)據(jù)。它具有永久性并可以由人或機器閱讀。通常僅用于描述人工可讀的內(nèi)容。例如，技術(shù)文件、設(shè)計文件、版本說明文件。3.2文檔（集）；文檔編制documentation一個或多個相關(guān)文檔的集合。3.3文檔計劃documentationplan一個描述文檔編制工作方法的管理用文檔。該計劃主要描述要編制什么類型的文檔，這些文檔的內(nèi)容是什么，何時編寫，由誰編寫，如何編寫，以及什么是影響期望結(jié)果的可用資源和外界因素。3.4文檔等級levelofdocumentation對所需文檔的一個說明，它指出文檔的范圍、內(nèi)容、格式及質(zhì)量，可以根據(jù)項目、費用、預(yù)期用途、作用范圍或其他因素選擇文檔等級。3.5軟件產(chǎn)品softwareproduct軟件開發(fā)過程的結(jié)果，并推出供用戶使用的軟件實體。4軟件文檔的作用a)管理依據(jù)；b)任務(wù)之間聯(lián)系的憑證；c)質(zhì)量保證；d)培訓(xùn)與參考；e)軟件維護支持；f)歷史檔案。4.1管理依據(jù)在軟件開過過程中，管理者必須了解開發(fā)進度、存在的問題和預(yù)期目標。每一階段計劃安排的定期報告提供了項目的可見性。定期報告還提醒各級管理者注意該部門對項目承擔(dān)的責(zé)任以及該部門效率的重要性。開發(fā)文檔規(guī)定若干個檢查點和進度表，使管理者可以評定項目的進度，如果開發(fā)文檔有遺漏，不完善，或內(nèi)容陳舊，則管理者將失去跟蹤和控制項目的重要依據(jù)。4.2任務(wù)之間聯(lián)系的憑證大多數(shù)軟件開發(fā)項目通常被劃分成若干個任務(wù)，并由不同的小組去完成。學(xué)科方面的專家建立項目，分析員闡述系統(tǒng)需求，設(shè)計員為程序員制定總體設(shè)計，程序員編制詳細的程序代碼，質(zhì)量保證專家和審查員評價整個系統(tǒng)性能和功能的完整性，負責(zé)維護的程序員改進各種操作或增強某些功能。這些人員需要的互相聯(lián)系是通過文檔資料的復(fù)制、分發(fā)和引用而實現(xiàn)的，因而，任務(wù)之間的聯(lián)系是文檔的一個重要功能。大多數(shù)系統(tǒng)開發(fā)方法為任務(wù)的聯(lián)系規(guī)定了一些正式文檔。分析員向設(shè)計員提供正式需求規(guī)格說明，設(shè)計員向程序員提供正式設(shè)計規(guī)格說在軟件開發(fā)的整個過程中，應(yīng)充分體現(xiàn)文檔的作用和限制，即文檔應(yīng)指導(dǎo)全部開發(fā)過程。文檔標準應(yīng)被標識和使用應(yīng)盡可能地采納現(xiàn)行的標準，若沒有合適的現(xiàn)行標準，必要時應(yīng)研制適用的標準或指南。應(yīng)規(guī)定支持工具工具有助于開發(fā)和維護軟件產(chǎn)品，包括文檔。因此盡可能地使用工具是經(jīng)濟的、可行的。附錄A中的檢查表為制定策略條款或評估現(xiàn)有策略條款的有效性和完整性提供幫助。7制訂文檔編制標準和指南在一個機構(gòu)內(nèi)部，應(yīng)采用一些標準和指南：——軟件生存期模型；——文檔類型和相互關(guān)系；——文檔質(zhì)量。這些標準和指南決定如何實現(xiàn)文檔任務(wù)，將提供一些準則以評價機構(gòu)內(nèi)所產(chǎn)生的軟件文檔的完整性、可用性和適合性。盡可能地采用現(xiàn)行的國家和國際標準，若現(xiàn)行的標準不適用，機構(gòu)應(yīng)制訂自己的標準。7.1選擇軟件生存期模型現(xiàn)有的一些軟件生存期模型，對于不同的階段有不同的詞匯，從軟件文檔的觀點來看，采用哪種模型都無關(guān)緊要，只要階段和相應(yīng)的文檔是清晰定義的、已計劃的，并且對于任何具體軟件項目是能遵循的。因此，管理者應(yīng)選擇一個軟件生存期模型并保證該模型在他們機構(gòu)內(nèi)是適用的。管理者將會發(fā)現(xiàn)所進行的階段和相應(yīng)任務(wù)的定義有助于監(jiān)控軟件項目的進展。相應(yīng)于特定階段生成的文檔可用作該階段的評審、通過和完成的檢驗點，而這種檢驗應(yīng)在下一階段開始前進行。7.2規(guī)定文檔類型和內(nèi)容下面給出軟件文檔主要類型的大綱，這個大綱不是詳盡的或最后的，但適合作為主要類型軟件文檔的檢驗表。而管理者應(yīng)規(guī)定何時定義他們的標準文檔類型。軟件文檔歸入如下三種類別：a)開發(fā)文檔——描述開發(fā)過程本身；b)產(chǎn)品文檔——描述開發(fā)過程的產(chǎn)物；c)管理文檔——記錄項目管理的信息。7.2.1開發(fā)文檔開發(fā)文檔是描述軟件開發(fā)過程，包括軟件需求、軟件設(shè)計、軟件測試、保證軟件質(zhì)量的一類文檔，開發(fā)文檔也包括軟件的詳細技術(shù)描述（程序邏輯、程序間相互關(guān)系、數(shù)據(jù)格式和存儲等）。開發(fā)文檔起到如下五種作用：a)它們是軟件開發(fā)過程中包含的所有階段之間的通信工具，它們記錄生成軟件需求、設(shè)計、編碼和測試的詳細規(guī)定和說明；b)它們描述開發(fā)小組的職責(zé)。通過規(guī)定軟件、主題事項、文檔編制、質(zhì)量保證人員以及包含在開發(fā)過程中任何其他事項的角色來定義做直截了當(dāng)、如何做和何時做；c)它們用作檢驗點而允許管理者評定開發(fā)進度。如果開發(fā)文檔丟失、不完整或過時，管理者將失去跟蹤和控制軟件項目的一個重要工具；d)它們形成了維護人員所要求的基本的軟件支持文檔。而這些支持文檔可作為產(chǎn)品文檔的一部分；e)它們記錄軟件開發(fā)的歷史?；镜拈_發(fā)文檔是：——可行性研究和項目任務(wù)書；——需求規(guī)格說明；——功能規(guī)格說明；——設(shè)計規(guī)格說明，包括程序和數(shù)據(jù)規(guī)格說明；——開發(fā)計劃；——軟件集成和測試計劃；——質(zhì)量保證計劃、標準、進度；安全和測試信息。7.2.2產(chǎn)品文檔產(chǎn)品文檔規(guī)定關(guān)于軟件產(chǎn)品的使用、維護、增強、轉(zhuǎn)換和傳輸?shù)男畔?。產(chǎn)品的文檔起到如下三種作用：a)為使用和運行軟件產(chǎn)品的任何人規(guī)定培訓(xùn)和參考信息；b)使得那些未參加開發(fā)本軟件的程序員維護它；c)促進軟件產(chǎn)品的市場流通或提高可接受性。產(chǎn)品文檔用于下列類型的讀者：——用戶——他們利用軟件輸入數(shù)據(jù)、檢索信息和解決問題；——運行者——他們在計算機系統(tǒng)上運行軟件；——維護人員——他們維護、增強或變更軟件。產(chǎn)品文檔包括如下內(nèi)容：——用于管理者的指南和資料，他們監(jiān)督軟件的使用；——宣傳資料通告軟件產(chǎn)品的可用性并詳細說明它的功能、運行環(huán)境等；——般信息對任何有興趣的人描述軟件產(chǎn)品。基本的產(chǎn)品文檔包括：——培訓(xùn)手冊；——參考手冊和用戶指南；——軟件支持手冊；——產(chǎn)品手冊和信息廣告。7.2.3管理文檔這種文檔建立在項目管理信息的基礎(chǔ)上，諸如：——開發(fā)過程的每個階段的進度和進度變更的記錄；——軟件變更情況的記錄；——相對于開發(fā)的判定記錄；——職責(zé)定義。這種文檔從管理的角度規(guī)定涉及軟件生存的信息。相關(guān)文檔的詳細規(guī)定和編寫格式見GB8567。7.3確定文檔的質(zhì)量等級僅僅依據(jù)規(guī)章、傳統(tǒng)的做法或合同的要求去制作文檔是不夠的。管理者還必須確定文檔的質(zhì)量要求以及如何達到和保證質(zhì)量要求。質(zhì)量要求的確定取決于可得到的資源、項目的大小和風(fēng)險，可以對該產(chǎn)品的每個文檔的格式及詳細程度作出明確的規(guī)定。每個文檔的質(zhì)量必須在文檔計劃期間就有明確的規(guī)定。文檔的質(zhì)量可以按文檔的形式和列出的要墳劃分為四級。最低限度文檔（1級文檔）1級文檔適合開發(fā)工作量低于一個人月的開發(fā)者自用程序。該文檔應(yīng)包含程序清單、開發(fā)記錄、測試數(shù)據(jù)和程序簡介。內(nèi)部文檔（2級文檔）2級文檔可用于在精心研究后被認為似乎沒有與其他用戶共享資源的專用程序。除1級文檔提供的信息外，2級文檔還包括程序清單內(nèi)足夠的注釋以幫助用戶安裝和使用程序。工作文檔（3級文檔）3級文檔適合于由同一單位內(nèi)若干人聯(lián)合開發(fā)的程序，或可被其他單位使用的程序。正式文檔（4級文檔）4級文檔適合那些要正式發(fā)行供普遍使用的軟件產(chǎn)品。關(guān)鍵性程序或具有重復(fù)管理應(yīng)用性質(zhì)（如工資計算）的程序需要4級文檔。4級文檔遵守GB8567的有關(guān)規(guī)定。質(zhì)量方面需要考慮的問題即要包含文檔的結(jié)構(gòu)，也要包含文檔的內(nèi)容。文檔內(nèi)容可以根據(jù)正確性、完整性和明確性來判斷。而文檔結(jié)構(gòu)由各個組成部分的順序和總體安排的簡單性來測定。要達到這四個質(zhì)量等級，需要的投入和資源逐級增加，質(zhì)量保證機構(gòu)必須處于適當(dāng)?shù)男姓匚灰员ＷC達到期望的質(zhì)量等級。8文檔編制計劃文檔計劃可以是整個項目計劃的一部分或是一個獨立的文檔。應(yīng)該編寫文檔計劃并把它分發(fā)給全體開發(fā)組成員，作為文檔重要性的具體依據(jù)和管理部門文檔工作責(zé)任的備忘錄。對于小的、非正式的項目，文檔計劃可能只有一頁紙；對于較大的項目，文檔計劃可能是一個綜合性的正式文檔，這樣的文檔計劃應(yīng)遵循各項嚴格的標準及正規(guī)的評審和批準過程。編制計劃的工作應(yīng)及早開始，對計劃的評審應(yīng)貫穿項目的全過程。如同任何別的計劃一樣，文檔計劃指出未來的各項活動，當(dāng)需要修改時必須加以修改。導(dǎo)致對計劃作適當(dāng)修改的常規(guī)評審應(yīng)作為該項目工作的一部分，所有與該計劃有關(guān)的人員都應(yīng)得到文檔計劃。文檔計劃一般包括以下幾方面內(nèi)容：列出應(yīng)編制文檔的目錄；提示編制文檔應(yīng)參考的標準；指定文檔管理員；提供編制文檔所需要的條件，落實文檔編寫人員、所需經(jīng)費以及編制工具等；明確保