軟件管理指引

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

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)最新版本的可能性.GB 8566-88計(jì)算機(jī)軟件開發(fā)標(biāo)準(zhǔn)GB 8567-88計(jì)算機(jī)軟件產(chǎn)品開發(fā)文件編制指南GB/T 11457-1995軟件工程術(shù)語3定義本標(biāo)準(zhǔn)采用以下定義,其他定義見GB/T 114573.1 文檔 document一種數(shù)據(jù)媒體和其上所記錄的數(shù)據(jù).它具有永久性并可以由人或機(jī)器閱讀.通 常僅用于描述人工可讀的內(nèi)容.例如,技術(shù)文件、設(shè)計(jì)文件、版本說明文件.3.2 文檔集；文檔編制documentation一個(gè)或多個(gè)相關(guān)文檔的集合.3.3 文檔計(jì)戈U

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

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

5、責(zé)維護(hù)的程序員改良各種操作或增強(qiáng)某些功能.這些人員需要的互相聯(lián)系是通過文檔資料的復(fù)制、分發(fā)和引用而實(shí)現(xiàn)的,因而,任務(wù)之間的聯(lián)系是文檔的一個(gè)重要功能.大多數(shù)系統(tǒng)開發(fā)方法為任務(wù)的聯(lián)系規(guī)定了 一些正式文檔.分析員向設(shè)計(jì)員提供正式需求規(guī)格說明,設(shè)計(jì)員向程序員提供正式 設(shè)計(jì)規(guī)格說明,等等.4.3 質(zhì)量保證那些負(fù)責(zé)軟件質(zhì)量保證和評(píng)估系統(tǒng)性能的人員需要程序規(guī)格說明、測(cè)試和評(píng)估 方案、測(cè)試該系統(tǒng)用的各種質(zhì)量標(biāo)準(zhǔn)以及關(guān)于期望系統(tǒng)完成什么功能和系統(tǒng)怎樣實(shí) 現(xiàn)這些功能的清楚說明；必須制訂測(cè)試方案和測(cè)試規(guī)程,并報(bào)告測(cè)試結(jié)果；他們還 必須說明和評(píng)估完全、限制、計(jì)算、檢驗(yàn)例行程序及其他限制技術(shù).這些文檔的提 供可滿足質(zhì)量

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

7、到各種新的系統(tǒng)環(huán)境中.5治理者的作用治理者嚴(yán)格要求軟件開發(fā)人員和編制組完成文檔編制,并且在策略、標(biāo)準(zhǔn)、規(guī) 程、資源分配和編制方案方面給予支持.a治理者對(duì)文檔工作的責(zé)任.治理者要熟悉到正式或非正式文檔都是重要的, 還要熟悉到文檔工作必須包括文檔方案、編寫、修改、形成、分發(fā)和維護(hù)等 各個(gè)方面.b治理者對(duì)文檔工作的支持.治理者應(yīng)為編寫文檔的人員提供指導(dǎo)和實(shí)際鼓 勵(lì),并使各種資源有效地用于文檔開發(fā).c治理者的主要責(zé)任：1建立編制、登記、出版系統(tǒng)文檔和軟件文檔的各種策略；2把文檔方案作為整個(gè)開發(fā)工作的一個(gè)組成局部； 3建立確定文檔質(zhì)量、測(cè)試質(zhì)量和評(píng)審質(zhì)量的各種方法的規(guī)程;4為文檔的各個(gè)方面 確定和準(zhǔn)備各

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

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

10、同類型的文檔.d文檔效應(yīng)應(yīng)貫穿到軟件的整個(gè)開發(fā)過程中在軟件開發(fā)的整個(gè)過程中, 應(yīng)充分表達(dá)文檔的作用和限制,即文檔應(yīng)指導(dǎo)全部開發(fā)過程.e文檔標(biāo)準(zhǔn)應(yīng)被標(biāo)識(shí)和使用應(yīng)盡可能地采納現(xiàn)行的標(biāo)準(zhǔn), 假設(shè)沒有適宜的現(xiàn)行標(biāo)準(zhǔn), 必要時(shí)應(yīng)研制適用的 標(biāo)準(zhǔn)或指南.f應(yīng)規(guī)定支持工具工具有助于開發(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)和指南： 軟件生存期模型； 文檔類型和相互關(guān)系； 文檔質(zhì)量.這些標(biāo)準(zhǔn)和指南決定如何實(shí)現(xiàn)文檔任務(wù),將提供一些準(zhǔn)那么以評(píng)價(jià)機(jī)構(gòu)內(nèi)所產(chǎn)生 的

11、軟件文檔的完整性、可用性和適合性.盡可能地采用現(xiàn)行的國(guó)家和國(guó)際標(biāo)準(zhǔn),假設(shè)現(xiàn)行的標(biāo)準(zhǔn)不適用,機(jī)構(gòu)應(yīng)制訂自己 的標(biāo)準(zhǔn).7.1 選擇軟件生存期模型現(xiàn)有的一些軟件生存期模型,對(duì)于不同的階段有不同的詞匯,從軟件文檔的觀 點(diǎn)來看,采用哪種模型都無關(guān)緊要,只要階段和相應(yīng)的文檔是清楚定義的、已方案 的,并且對(duì)于任何具體軟件工程是能遵循的.因此,治理者應(yīng)選擇一個(gè)軟件生存期 模型并保證該模型在他們機(jī)構(gòu)內(nèi)是適用的.治理者將會(huì)發(fā)現(xiàn)所進(jìn)行的階段和相應(yīng)任務(wù)的定義有助于監(jiān)控軟件工程的進(jìn)展. 相應(yīng)于特定階段生成的文檔可用作該階段的評(píng)審、通過和完成的檢驗(yàn)點(diǎn),而這種檢 驗(yàn)應(yīng)在下一階段開始前進(jìn)行.7.2 規(guī)定文檔類型和內(nèi)容下面給出

12、軟件文檔主要類型的大綱,這個(gè)大綱不是詳盡的或最后的,但適合作 為主要類型軟件文檔的檢驗(yàn)表.而治理者應(yīng)規(guī)定何時(shí)定義他們的標(biāo)準(zhǔn)文檔類型.軟件文檔歸入如下三種類別：a開發(fā)文檔一一描述開發(fā)過程本身；b產(chǎn)品文檔一一描述開發(fā)過程的產(chǎn)物；c治理文檔一一記錄工程治理的信息.7.2.1 開發(fā)文檔開發(fā)文檔是描述軟件開發(fā)過程,包括軟件需求、軟件設(shè)計(jì)、軟件測(cè)試、保證軟 件質(zhì)量的一類文檔,開發(fā)文檔也包括軟件的詳細(xì)技術(shù)描述程序邏輯、程序間相互 關(guān)系、數(shù)據(jù)格式和存儲(chǔ)等.開發(fā)文檔起到如下五種作用：a它們是軟件開發(fā)過程中包含的所有階段之間的通信工具,它們記錄生成軟件需求、設(shè)計(jì)、編碼和測(cè)試的詳細(xì)規(guī)定和說明；b它們描述開發(fā)小組的責(zé)

13、任.通過規(guī)定軟件、主題事項(xiàng)、文檔編制、質(zhì)量保證 人員以及包含在開發(fā)過程中任何其他事項(xiàng)的角色來定義做直截了當(dāng)、如何做和何時(shí)做；c它們用作檢驗(yàn)點(diǎn)而允許治理者評(píng)定開發(fā)進(jìn)度.如果開發(fā)文檔喪失、不完整或過時(shí),治理者將失去跟蹤和限制軟件工程的一個(gè)重要工具；d它們形成了維護(hù)人員所要求的根本的軟件支持文檔.而這些支持文檔可作為產(chǎn)品文檔的一局部；e它們記錄軟件開發(fā)的歷史.根本的開發(fā)文檔是：產(chǎn)一可行性研究和工程任務(wù)書；一一需求規(guī)格說明；功能規(guī)格說明; 設(shè)計(jì)規(guī)格說明,包括程序和數(shù)據(jù)規(guī)格說明； 開發(fā)方案； 軟件集成和測(cè)試方案； 質(zhì)量保證方案、標(biāo)準(zhǔn)、進(jìn)度；平安和測(cè)試信息.7.2.2 產(chǎn)品文檔產(chǎn)品文檔規(guī)定關(guān)于軟件產(chǎn)品的使

14、用、維護(hù)、增強(qiáng)、轉(zhuǎn)換和傳輸?shù)男畔?產(chǎn)品的文檔起到如下三種作用：a為使用和運(yùn)行軟件產(chǎn)品的任何人規(guī)定培訓(xùn)和參考信息；b使得那些未參加開發(fā)本軟件的程序員維護(hù)它；c促進(jìn)軟件產(chǎn)品的市場(chǎng)流通或提升可接受性.產(chǎn)品文檔用于以下類型的讀者： 用戶一一他們利用軟件輸入數(shù)據(jù)、檢索信息和解決問題； 運(yùn)行者一一他們?cè)谟?jì)算機(jī)系統(tǒng)上運(yùn)行軟件； 維護(hù)人員一一他們維護(hù)、增強(qiáng)或變更軟件.產(chǎn)品文檔包括如下內(nèi)容： 用于治理者的指南和資料,他們監(jiān)督軟件的使用； 宣傳資料 通告軟件產(chǎn)品的可用性并詳細(xì)說明它的功能、運(yùn)行環(huán)境等; 一 般信息 對(duì)任何有興趣的人描述軟件產(chǎn)品.根本的產(chǎn)品文檔包括： 培訓(xùn)手冊(cè)； 參考手冊(cè)和用戶指南； 軟件支持手冊(cè)；

15、 產(chǎn)品手冊(cè)和信息廣告.7.2.3 治理文檔這種文檔建立在工程治理信息的根底上,諸如：開發(fā)過程的每個(gè)階段的進(jìn)度和進(jìn)度變更的記錄；軟件變更情況的記錄；相對(duì)于開發(fā)的判定記錄；責(zé)任定義.這種文檔從治理的角度規(guī)定涉及軟件生存的信息.相關(guān)文檔的詳細(xì)規(guī)定和編寫格式見 GB 8567.7.3確定文檔的質(zhì)量等級(jí)僅僅依據(jù)規(guī)章、傳統(tǒng)的做法或合同的要求去制作文檔是不夠的.治理者還必須 確定文檔的質(zhì)量要求以及如何到達(dá)和保證質(zhì)量要求.質(zhì)量要求確實(shí)定取決于可得到的資源、工程的大小和風(fēng)險(xiǎn),可以對(duì)該產(chǎn)品的每 個(gè)文檔的格式及詳細(xì)程度作出明確的規(guī)定.每個(gè)文檔的質(zhì)量必須在文檔方案期間就有明確的規(guī)定.文檔的質(zhì)量可以按文檔 的形式和列出

16、的要墳劃分為四級(jí).最低限度文檔1級(jí)文檔1級(jí)文檔適合開發(fā)工作量低于一個(gè)人月的開發(fā)者自 用程序.該文檔應(yīng)包含程序清單、開發(fā)記錄、測(cè)試數(shù)據(jù)和程序簡(jiǎn)介.內(nèi)部文檔2級(jí)文檔2級(jí)文檔可用于在精心研究后被認(rèn)為似乎沒有與其他用 戶共享資源的專用程序.除 1級(jí)文檔提供的信息外,2級(jí)文檔還包括程序清單內(nèi)足 夠的注釋以幫助用戶安裝和使用程序.工作文檔3級(jí)文檔3級(jí)文檔適合于由同一單位內(nèi)假設(shè)干人聯(lián)合開發(fā)的程序, 或可被其他單位使用的程序.正式文檔4級(jí)文檔4級(jí)文檔適合那些要正式發(fā)行供普遍使用的軟件產(chǎn)品.關(guān)鍵性程序或具有重復(fù)治理應(yīng)用性質(zhì)如工資計(jì)算的程序需要4級(jí)文檔.4級(jí)文檔遵守GB 8567的有關(guān)規(guī)定.質(zhì)量方面需要考慮的問題

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