文檔管理指引

1、軟件文檔管理指南1范圍本標(biāo)準(zhǔn)為那些對(duì)軟件或基于軟件的產(chǎn)品的開(kāi)發(fā)負(fù)有職責(zé)的管理者提供軟件文檔的管理指南。本標(biāo)準(zhǔn)的目的在于協(xié)助管理者在他們的機(jī)構(gòu)中產(chǎn)生有效的文檔。本標(biāo)準(zhǔn)涉及策略、標(biāo)準(zhǔn)、規(guī)程、資源和計(jì)劃，管理者必須關(guān)注這些內(nèi)容，以便有效地管理軟件文檔。本標(biāo)準(zhǔn)期望應(yīng)用于各種類(lèi)型的軟件，從簡(jiǎn)單的程序到復(fù)雜的軟件系統(tǒng)。并期望覆蓋各種類(lèi)型的軟件文檔，作用于軟件生存期的各個(gè)階段。不論項(xiàng)目的大小，軟件文檔管理的原則是一致的。對(duì)于小項(xiàng)目，可以不采用本標(biāo)準(zhǔn)中規(guī)定的有關(guān)細(xì)節(jié)。管理者可剪裁這些內(nèi)容以滿(mǎn)足他們的特殊需要。本標(biāo)準(zhǔn)是針對(duì)文檔編制管理而提出的，不涉及軟件文檔的內(nèi)容和編排。2引用標(biāo)準(zhǔn)下列標(biāo)準(zhǔn)所包含的條文，通過(guò)在本

2、標(biāo)準(zhǔn)中引用而構(gòu)成為本標(biāo)準(zhǔn)的條文。本標(biāo)準(zhǔn)出版時(shí)，所示版本均為有效，所有標(biāo)準(zhǔn)都會(huì)被修訂，使用本標(biāo)準(zhǔn)的各方應(yīng)探討使用下列標(biāo)準(zhǔn)最新版本的可能性。GB8566-88計(jì)算機(jī)軟件開(kāi)發(fā)規(guī)范GB8567-88計(jì)算機(jī)軟件產(chǎn)品開(kāi)發(fā)文件編制指南GB/T11457-1995軟件工程術(shù)語(yǔ)3定義本標(biāo)準(zhǔn)采用下列定義，其他定義見(jiàn)GB/T11457。3.1 文檔document一種數(shù)據(jù)媒體和其上所記錄的數(shù)據(jù)。它具有永久性并可以由人或機(jī)器閱讀。通常僅用于描述人工可讀的內(nèi)容。例如，技術(shù)文件、設(shè)計(jì)文件、版本說(shuō)明文件。3.2 文檔（集）；文檔編制documentation一個(gè)或多個(gè)相關(guān)文檔的集合。3.3 文檔計(jì)戈Udocumentati

3、onplan一個(gè)描述文檔編制工作方法的管理用文檔。該計(jì)劃主要描述要編制什么類(lèi)型的文檔，這些文檔的內(nèi)容是什么，何時(shí)編寫(xiě)，由誰(shuí)編寫(xiě)，如何編寫(xiě)，以及什么是影響期望結(jié)果的可用資源和外界因素。3.4 文檔等級(jí)levelofdocumentation對(duì)所需文檔的一個(gè)說(shuō)明，它指出文檔的范圍、內(nèi)容、格式及質(zhì)量，可以根據(jù)項(xiàng)目、費(fèi)用、預(yù)期用途、作用范圍或其他因素選擇文檔等級(jí)。3.5 軟件產(chǎn)品softwareproduct軟件開(kāi)發(fā)過(guò)程的結(jié)果，并推出供用戶(hù)使用的軟件實(shí)體。4軟件文檔的作用a）管理依據(jù)；b）任務(wù)之間聯(lián)系的憑證；c）質(zhì)量保證；d）培訓(xùn)與參考；e）軟件維護(hù)支持；f）歷史檔案。4.1 管理依據(jù)在軟件開(kāi)過(guò)過(guò)程中

4、，管理者必須了解開(kāi)發(fā)進(jìn)度、存在的問(wèn)題和預(yù)期目標(biāo)。每一階段計(jì)劃安排的定期報(bào)告提供了項(xiàng)目的可見(jiàn)性。定期報(bào)告還提醒各級(jí)管理者注意該部門(mén)對(duì)項(xiàng)目承擔(dān)的責(zé)任以及該部門(mén)效率的重要性。開(kāi)發(fā)文檔規(guī)定若干個(gè)檢查點(diǎn)和進(jìn)度表，使管理者可以評(píng)定項(xiàng)目的進(jìn)度，如果開(kāi)發(fā)文檔有遺漏，不完善，或內(nèi)容陳舊，則管理者將失去跟蹤和控制項(xiàng)目的重要依據(jù)。4.2 任務(wù)之間聯(lián)系的憑證大多數(shù)軟件開(kāi)發(fā)項(xiàng)目通常被劃分成若干個(gè)任務(wù)，并由不同的小組去完成。學(xué)科方面的專(zhuān)家建立項(xiàng)目，分析員闡述系統(tǒng)需求，設(shè)計(jì)員為程序員制定總體設(shè)計(jì)，程序員編制詳細(xì)的程序代碼，質(zhì)量保證專(zhuān)家和審查員評(píng)價(jià)整個(gè)系統(tǒng)性能和功能的完整性，負(fù)責(zé)維護(hù)的程序員改進(jìn)各種操作或增強(qiáng)某些功能。這些人

5、員需要的互相聯(lián)系是通過(guò)文檔資料的復(fù)制、分發(fā)和引用而實(shí)現(xiàn)的，因而，任務(wù)之間的聯(lián)系是文檔的一個(gè)重要功能。大多數(shù)系統(tǒng)開(kāi)發(fā)方法為任務(wù)的聯(lián)系規(guī)定了一些正式文檔。分析員向設(shè)計(jì)員提供正式需求規(guī)格說(shuō)明，設(shè)計(jì)員向程序員提供正式設(shè)計(jì)規(guī)格說(shuō)明，等等。4.3 質(zhì)量保證那些負(fù)責(zé)軟件質(zhì)量保證和評(píng)估系統(tǒng)性能的人員需要程序規(guī)格說(shuō)明、測(cè)試和評(píng)估計(jì)劃、測(cè)試該系統(tǒng)用的各種質(zhì)量標(biāo)準(zhǔn)以及關(guān)于期望系統(tǒng)完成什么功能和系統(tǒng)怎樣實(shí)現(xiàn)這些功能的清晰說(shuō)明；必須制訂測(cè)試計(jì)劃和測(cè)試規(guī)程，并報(bào)告測(cè)試結(jié)果；他們還必須說(shuō)明和評(píng)估完全、控制、計(jì)算、檢驗(yàn)例行程序及其他控制技術(shù)。這些文檔的提供可滿(mǎn)足質(zhì)量保證人員和審查人員上述工作的需要。4.4 培訓(xùn)與參考軟件文檔

6、的另一個(gè)功能是使系統(tǒng)管理員、操作員、用戶(hù)、管理者和其他有關(guān)人員了解系統(tǒng)如何工作，以及為了達(dá)到他們的各自的目的，如何使用系統(tǒng)。4.5 軟件維護(hù)支持維護(hù)人員需要軟件系統(tǒng)的詳細(xì)說(shuō)明以幫助他們熟悉系統(tǒng)，找出并修正錯(cuò)誤，改進(jìn)系統(tǒng)以適應(yīng)用戶(hù)需求的變化或適應(yīng)系統(tǒng)環(huán)境的變化。4.6 歷史檔案軟件文檔可用作未來(lái)項(xiàng)目的一種資源。通常文檔記載系統(tǒng)的開(kāi)發(fā)歷史，可使有關(guān)系統(tǒng)結(jié)構(gòu)的基本思想為以后的項(xiàng)目利用。系統(tǒng)開(kāi)發(fā)人員通過(guò)審閱以前的系統(tǒng)以查明什么部分已試驗(yàn)過(guò)了，什么部分運(yùn)行得很好，什么部分因某種原因難以運(yùn)行而被排除。良好的系統(tǒng)文檔有助于把程序移植和轉(zhuǎn)移到各種新的系統(tǒng)環(huán)境中。5管理者的作用管理者嚴(yán)格要求軟件開(kāi)發(fā)人員和編制組

7、完成文檔編制，并且在策略、標(biāo)準(zhǔn)、規(guī)程、資源分配和編制計(jì)劃方面給予支持。a）管理者對(duì)文檔工作的責(zé)任。管理者要認(rèn)識(shí)到正式或非正式文檔都是重要的，還要認(rèn)識(shí)到文檔工作必須包括文檔計(jì)劃、編寫(xiě)、修改、形成、分發(fā)和維護(hù)等各個(gè)方面。b）管理者對(duì)文檔工作的支持。管理者應(yīng)為編寫(xiě)文檔的人員提供指導(dǎo)和實(shí)際鼓勵(lì)，并使各種資源有效地用于文檔開(kāi)發(fā)。c）管理者的主要職責(zé)：1）建立編制、登記、出版系統(tǒng)文檔和軟件文檔的各種策略；2）把文檔計(jì)劃作為整個(gè)開(kāi)發(fā)工作的一個(gè)組成部分；3）建立確定文檔質(zhì)量、測(cè)試質(zhì)量和評(píng)審質(zhì)量的各種方法的規(guī)程；4）為文檔的各個(gè)方面確定和準(zhǔn)備各種標(biāo)準(zhǔn)和指南；5）積極支持文檔工作以形成在開(kāi)發(fā)工作中自覺(jué)編制文檔的團(tuán)

8、隊(duì)風(fēng)氣；6）不斷檢查已建立起來(lái)的過(guò)程，以保證符合策略和各種規(guī)程并遵守有關(guān)標(biāo)準(zhǔn)和指南。通常，項(xiàng)目管理者在項(xiàng)目開(kāi)發(fā)前應(yīng)決定如下事項(xiàng)：要求哪些類(lèi)型的文檔；提供多少種文檔；文檔包含的內(nèi)容；達(dá)到何種級(jí)別的質(zhì)量水平；何時(shí)產(chǎn)生何種文檔；如何保存、維護(hù)文檔以及如何進(jìn)行通信。如果一個(gè)軟件合同是有效的，應(yīng)要求文檔滿(mǎn)足所接受的標(biāo)準(zhǔn)，并規(guī)定所提供的文檔類(lèi)型、每種文檔的質(zhì)量水平以及評(píng)審和通過(guò)的規(guī)程。6制訂文檔編制策略文檔策略是由上級(jí)（資深）管理者新任務(wù)并支持的，對(duì)下級(jí)開(kāi)發(fā)單位或開(kāi)發(fā)人員提供指導(dǎo)。策略規(guī)定主要的方向不是做什么或如何做的詳細(xì)說(shuō)明。一般說(shuō)來(lái)，文檔編制策略陳述要明確，并通告到每個(gè)人且理解它，進(jìn)而使策略被他們貫徹

9、實(shí)施。支持有效文檔策略的基本條件：a）文檔需要覆蓋整個(gè)軟件生存期在項(xiàng)目早期幾個(gè)階段就要求有文檔，而且在貫穿軟件開(kāi)發(fā)過(guò)程中必須是可用的和可維護(hù)的。在開(kāi)發(fā)完成后，文檔應(yīng)滿(mǎn)足軟件的使用、維護(hù)、增強(qiáng)、轉(zhuǎn)換或傳輸。b）文檔應(yīng)是可管理的指導(dǎo)和控制文檔的獲得維護(hù)，管理者和發(fā)行專(zhuān)家應(yīng)準(zhǔn)備文檔產(chǎn)品、進(jìn)度、可靠性、資源,質(zhì)量保證和評(píng)審規(guī)程的詳細(xì)計(jì)劃大綱。c）文檔應(yīng)適合于它的讀者讀者可能是管理者、分析員、無(wú)計(jì)算機(jī)經(jīng)驗(yàn)的專(zhuān)業(yè)人員、維護(hù)人員、文書(shū)人員等。根據(jù)任務(wù)的執(zhí)行，他們要求不同的材料表示和不同的詳細(xì)程度。針對(duì)不同的讀者，發(fā)行專(zhuān)家應(yīng)負(fù)責(zé)設(shè)計(jì)不同類(lèi)型的文檔。d）文檔效應(yīng)應(yīng)貫穿到軟件的整個(gè)開(kāi)發(fā)過(guò)程中在軟件開(kāi)發(fā)的整個(gè)過(guò)程中

10、，應(yīng)充分體現(xiàn)文檔的作用和限制，即文檔應(yīng)指導(dǎo)全部開(kāi)發(fā)過(guò)程。e）文檔標(biāo)準(zhǔn)應(yīng)被標(biāo)識(shí)和使用應(yīng)盡可能地采納現(xiàn)行的標(biāo)準(zhǔn)，若沒(méi)有合適的現(xiàn)行標(biāo)準(zhǔn)，必要時(shí)應(yīng)研制適用的標(biāo)準(zhǔn)或指南。f）應(yīng)規(guī)定支持工具工具有助于開(kāi)發(fā)和維護(hù)軟件產(chǎn)品，包括文檔。因此盡可能地使用工具是經(jīng)濟(jì)的、可行的。附錄A中的檢查表為制定策略條款或評(píng)估現(xiàn)有策略條款的有效性和完整性提供幫助。7制訂文檔編制標(biāo)準(zhǔn)和指南在一個(gè)機(jī)構(gòu)內(nèi)部，應(yīng)采用一些標(biāo)準(zhǔn)和指南： 軟件生存期模型； 文檔類(lèi)型和相互關(guān)系； 文檔質(zhì)量。這些標(biāo)準(zhǔn)和指南決定如何實(shí)現(xiàn)文檔任務(wù)，將提供一些準(zhǔn)則以評(píng)價(jià)機(jī)構(gòu)內(nèi)所產(chǎn)生的軟件文檔的完整性、可用性和適合性。盡可能地采用現(xiàn)行的國(guó)家和國(guó)際標(biāo)準(zhǔn)，若現(xiàn)行的標(biāo)準(zhǔn)不適用

11、，機(jī)構(gòu)應(yīng)制訂自己的標(biāo)準(zhǔn)。7.1 選擇軟件生存期模型現(xiàn)有的一些軟件生存期模型，對(duì)于不同的階段有不同的詞匯，從軟件文檔的觀點(diǎn)來(lái)看，采用哪種模型都無(wú)關(guān)緊要，只要階段和相應(yīng)的文檔是清晰定義的、已計(jì)劃的，并且對(duì)于任何具體軟件項(xiàng)目是能遵循的。因此，管理者應(yīng)選擇一個(gè)軟件生存期模型并保證該模型在他們機(jī)構(gòu)內(nèi)是適用的。管理者將會(huì)發(fā)現(xiàn)所進(jìn)行的階段和相應(yīng)任務(wù)的定義有助于監(jiān)控軟件項(xiàng)目的進(jìn)展。相應(yīng)于特定階段生成的文檔可用作該階段的評(píng)審、通過(guò)和完成的檢驗(yàn)點(diǎn)，而這種檢驗(yàn)應(yīng)在下一階段開(kāi)始前進(jìn)行。7.2 規(guī)定文檔類(lèi)型和內(nèi)容下面給出軟件文檔主要類(lèi)型的大綱，這個(gè)大綱不是詳盡的或最后的，但適合作為主要類(lèi)型軟件文檔的檢驗(yàn)表。而管理者應(yīng)規(guī)

12、定何時(shí)定義他們的標(biāo)準(zhǔn)文檔類(lèi)型。軟件文檔歸入如下三種類(lèi)別：a）開(kāi)發(fā)文檔一一描述開(kāi)發(fā)過(guò)程本身；b）產(chǎn)品文檔一一描述開(kāi)發(fā)過(guò)程的產(chǎn)物；c）管理文檔一一記錄項(xiàng)目管理的信息。7.2.1 開(kāi)發(fā)文檔開(kāi)發(fā)文檔是描述軟件開(kāi)發(fā)過(guò)程，包括軟件需求、軟件設(shè)計(jì)、軟件測(cè)試、保證軟件質(zhì)量的一類(lèi)文檔，開(kāi)發(fā)文檔也包括軟件的詳細(xì)技術(shù)描述（程序邏輯、程序間相互關(guān)系、數(shù)據(jù)格式和存儲(chǔ)等）。開(kāi)發(fā)文檔起到如下五種作用：a）它們是軟件開(kāi)發(fā)過(guò)程中包含的所有階段之間的通信工具，它們記錄生成軟件需求、設(shè)計(jì)、編碼和測(cè)試的詳細(xì)規(guī)定和說(shuō)明；b）它們描述開(kāi)發(fā)小組的職責(zé)。通過(guò)規(guī)定軟件、主題事項(xiàng)、文檔編制、質(zhì)量保證人員以及包含在開(kāi)發(fā)過(guò)程中任何其他事項(xiàng)的角色來(lái)定

13、義做直截了當(dāng)、如何做和何時(shí)做；c）它們用作檢驗(yàn)點(diǎn)而允許管理者評(píng)定開(kāi)發(fā)進(jìn)度。如果開(kāi)發(fā)文檔丟失、不完整或過(guò)時(shí)，管理者將失去跟蹤和控制軟件項(xiàng)目的一個(gè)重要工具；d）它們形成了維護(hù)人員所要求的基本的軟件支持文檔。而這些支持文檔可作為產(chǎn)品文檔的一部分；e）它們記錄軟件開(kāi)發(fā)的歷史。基本的開(kāi)發(fā)文檔是：管一可行性研究和項(xiàng)目任務(wù)書(shū)；一一需求規(guī)格說(shuō)明；管一功能規(guī)格說(shuō)明；一一設(shè)計(jì)規(guī)格說(shuō)明，包括程序和數(shù)據(jù)規(guī)格說(shuō)明；一一開(kāi)發(fā)計(jì)劃；一一軟件集成和測(cè)試計(jì)劃；管一質(zhì)量保證計(jì)劃、標(biāo)準(zhǔn)、進(jìn)度；安全和測(cè)試信息。7.2.2 產(chǎn)品文檔產(chǎn)品文檔規(guī)定關(guān)于軟件產(chǎn)品的使用、維護(hù)、增強(qiáng)、轉(zhuǎn)換和傳輸?shù)男畔ⅰ．a(chǎn)品的文檔起到如下三種作用：a）為使用和運(yùn)

14、行軟件產(chǎn)品的任何人規(guī)定培訓(xùn)和參考信息；b）使得那些未參加開(kāi)發(fā)本軟件的程序員維護(hù)它；c）促進(jìn)軟件產(chǎn)品的市場(chǎng)流通或提高可接受性。產(chǎn)品文檔用于下列類(lèi)型的讀者： 用戶(hù)一一他們利用軟件輸入數(shù)據(jù)、檢索信息和解決問(wèn)題； 運(yùn)行者一一他們?cè)谟?jì)算機(jī)系統(tǒng)上運(yùn)行軟件； 維護(hù)人員一一他們維護(hù)、增強(qiáng)或變更軟件。產(chǎn)品文檔包括如下內(nèi)容： 用于管理者的指南和資料，他們監(jiān)督軟件的使用； 宣傳資料通告軟件產(chǎn)品的可用性并詳細(xì)說(shuō)明它的功能、運(yùn)行環(huán)境等； 一般信息對(duì)任何有興趣的人描述軟件產(chǎn)品?；镜漠a(chǎn)品文檔包括： 培訓(xùn)手冊(cè)； 參考手冊(cè)和用戶(hù)指南； 軟件支持手冊(cè)； 產(chǎn)品手冊(cè)和信息廣告。7.2.3管理文檔這種文檔建立在項(xiàng)目管理信息的基礎(chǔ)上，

15、諸如：開(kāi)發(fā)過(guò)程的每個(gè)階段的進(jìn)度和進(jìn)度變更的記錄； 軟件變更情況的記錄； 相對(duì)于開(kāi)發(fā)的判定記錄； 職責(zé)定義。這種文檔從管理的角度規(guī)定涉及軟件生存的信息。相關(guān)文檔的詳細(xì)規(guī)定和編寫(xiě)格式見(jiàn)GB8567。7.3確定文檔的質(zhì)量等級(jí)僅僅依據(jù)規(guī)章、傳統(tǒng)的做法或合同的要求去制作文檔是不夠的。管理者還必須確定文檔的質(zhì)量要求以及如何達(dá)到和保證質(zhì)量要求。質(zhì)量要求的確定取決于可得到的資源、項(xiàng)目的大小和風(fēng)險(xiǎn)，可以對(duì)該產(chǎn)品的每個(gè)文檔的格式及詳細(xì)程度作出明確的規(guī)定。每個(gè)文檔的質(zhì)量必須在文檔計(jì)劃期間就有明確的規(guī)定。文檔的質(zhì)量可以按文檔的形式和列出的要墳劃分為四級(jí)。最低限度文檔（1級(jí)文檔）1級(jí)文檔適合開(kāi)發(fā)工作量低于一個(gè)人月的開(kāi)發(fā)

16、者自用程序。該文檔應(yīng)包含程序清單、開(kāi)發(fā)記錄、測(cè)試數(shù)據(jù)和程序簡(jiǎn)介。內(nèi)部文檔（2級(jí)文檔）2級(jí)文檔可用于在精心研究后被認(rèn)為似乎沒(méi)有與其他用戶(hù)共享資源的專(zhuān)用程序。除1級(jí)文檔提供的信息外，2級(jí)文檔還包括程序清單內(nèi)足夠的注釋以幫助用戶(hù)安裝和使用程序。工作文檔（3級(jí)文檔）3級(jí)文檔適合于由同一單位內(nèi)若干人聯(lián)合開(kāi)發(fā)的程序，或可被其他單位使用的程序。正式文檔（4級(jí)文檔）4級(jí)文檔適合那些要正式發(fā)行供普遍使用的軟件產(chǎn)品。關(guān)鍵性程序或具有重復(fù)管理應(yīng)用性質(zhì)（如工資計(jì)算）的程序需要4級(jí)文檔。4級(jí)文檔遵守GB8567的有關(guān)規(guī)定。質(zhì)量方面需要考慮的問(wèn)題即要包含文檔的結(jié)構(gòu)，也要包含文檔的內(nèi)容。文檔內(nèi)容可以根據(jù)正確性、完整性和明確

17、性來(lái)判斷。而文檔結(jié)構(gòu)由各個(gè)組成部分的順序和總體安排的簡(jiǎn)單性來(lái)測(cè)定。要達(dá)到這四個(gè)質(zhì)量等級(jí)，需要的投入和資源逐級(jí)增加，質(zhì)量保證機(jī)構(gòu)必須處于適當(dāng)?shù)男姓匚灰员ＷC達(dá)到期望的質(zhì)量等級(jí)。8文檔編制計(jì)劃文檔計(jì)劃可以是整個(gè)項(xiàng)目計(jì)劃的一部分或是一個(gè)獨(dú)立的文檔。應(yīng)該編寫(xiě)文檔計(jì)劃并把它分發(fā)給全體開(kāi)發(fā)組成員，作為文檔重要性的具體依據(jù)和管理部門(mén)文檔工作責(zé)任的備忘錄。對(duì)于小的、非正式的項(xiàng)目，文檔計(jì)劃可能只有一頁(yè)紙；對(duì)于較大的項(xiàng)目，文檔計(jì)劃可能是一個(gè)綜合性的正式文檔，這樣的文檔計(jì)劃應(yīng)遵循各項(xiàng)嚴(yán)格的標(biāo)準(zhǔn)及正規(guī)的評(píng)審和批準(zhǔn)過(guò)程。編制計(jì)劃的工作應(yīng)及早開(kāi)始，對(duì)計(jì)劃的評(píng)審應(yīng)貫穿項(xiàng)目的全過(guò)程。如同任何別的計(jì)劃一樣，文檔計(jì)劃指出未來(lái)的各項(xiàng)活動(dòng)，當(dāng)需要修改時(shí)必須加以修改。導(dǎo)致對(duì)計(jì)劃作適當(dāng)修改的常規(guī)評(píng)審應(yīng)作為該項(xiàng)目工作的一部分，所有與該計(jì)劃有關(guān)的人員都應(yīng)得到文檔計(jì)劃。文檔計(jì)劃一般包括以下幾方面內(nèi)容：a）列出應(yīng)編制文檔的目錄；b）提示編