軟件文檔國家標(biāo)準(zhǔn)與寫作要求

1、浙江工業(yè)大學(xué)計算機(jī)學(xué)院 陸佳煒第三章 軟件文檔國家標(biāo)準(zhǔn)軟件文檔寫作主要內(nèi)容軟件產(chǎn)品開發(fā)文檔編制指南 軟件需求說明編制指南軟件測試文檔編制規(guī)范軟件文檔管理指南1、軟件產(chǎn)品開發(fā)文檔編制指南 軟件文檔國家標(biāo)準(zhǔn) 計算機(jī)軟件產(chǎn)品開發(fā)文檔編制指南 （GB 8567-1988） 計算機(jī)軟件需求說明編制指南 （GB 9385-1988） 計算機(jī)軟件測試文檔編制規(guī)范 （GB 9386-1988） 軟件文檔管理指南 （GB 16680-1996）2006年后計算機(jī)軟件產(chǎn)品開發(fā)文件編制指南（GBT8567-2006）計算機(jī)軟件測試文件編制規(guī)范（GBT9386-2008）軟件產(chǎn)品開發(fā)文件編制指南 計算機(jī)軟件產(chǎn)品開發(fā)文

2、檔編制指南是一份指導(dǎo)性文檔，目的是使得所編制的軟件文檔確實(shí)能夠起到應(yīng)該發(fā)揮的作用。指南對軟件文檔的意義和作用、文檔與讀者的關(guān)系、軟件生存周期與各種文檔的編制、文檔編制中的考慮因素、文檔編制的管理工作以及各種文檔的內(nèi)容要求都作了詳細(xì)描述，并給出了各類文檔的編寫提示。 軟件產(chǎn)品開發(fā)文件編制指南 根據(jù)該指南，一項計算機(jī)軟件的開發(fā)過程中，一般應(yīng)產(chǎn)生如下十四種文檔：（1）可行性研究報告（2）項目開發(fā)計劃（3）軟件需求說明書（4）數(shù)據(jù)要求說明書（5）概要設(shè)計說明書（6）詳細(xì)設(shè)計說明書（7）數(shù)據(jù)庫設(shè)計說明書（8）用戶手冊（9）操作手冊（10）模塊開發(fā)卷宗（11）測試計劃（12）測試分析報告（13）開發(fā)進(jìn)度月

3、報（14）項目開發(fā)總結(jié)報告 本指南不僅給出了這十四種文檔的編制指導(dǎo)，同時，本指南也是這十四種文檔編寫質(zhì)量的檢驗(yàn)準(zhǔn)則。2、軟件需求說明編制指南軟件需求說明編制指南 軟件需求說明編制指南 軟件需求說明編制指南 軟件需求說明編制指南 軟件需求說明編制指南為軟件需求的實(shí)踐提供了一個規(guī)范化的方法，主要描述了軟件需求說明（Software Requirements Specifications，簡稱SRS）所必須的內(nèi)容和質(zhì)量。 軟件需求文檔的編制目標(biāo) SRS對于軟件客戶來講，應(yīng)盡可能準(zhǔn)確地描述其所需要的產(chǎn)品；而對于軟件開發(fā)者，應(yīng)能準(zhǔn)確地理解客戶所需要的產(chǎn)品。 編制SRS的目標(biāo)可以概括為如下六個方面： （1

4、）在軟件產(chǎn)品完成目標(biāo)方面為客戶和開發(fā)者之間建立共同協(xié)議創(chuàng)立一個基礎(chǔ) （2）提高開發(fā)效率 （3）為成本計價和編制計劃進(jìn)度提供基礎(chǔ) （4）為確認(rèn)和驗(yàn)證提供一個基準(zhǔn) （5）便于移植 （6）作為不斷提高的基礎(chǔ)軟件需求文檔的基本要求 SRS是對要完成一定功能、性能的軟件產(chǎn)品、程序或一組程序的說明。因此對SRS的描述有兩項基本要求： （1）必須描述一定的功能、性能； （2）必須用確定的方法敘述這些功能、性能。 SRS作為軟件開發(fā)規(guī)范之一，對軟件開發(fā)的所有階段都起著非常重要的作用，但是需要注意的是，SRS不能超出其作用范圍，即除了SRS正確地定義所有軟件的需求之外，一般地SRS不描述任何設(shè)計、驗(yàn)證或項目管理

5、的細(xì)節(jié)。 軟件需求標(biāo)準(zhǔn)適用范圍 1. 指南適用對象 軟件客戶（Customers），以便精確地描述他們想獲得什么樣的產(chǎn)品。 軟件開發(fā)者（Suppliers），以便準(zhǔn)確地理解客戶需要什么樣的產(chǎn)品。 2. 指南目的 對于任一單位和（或）個人，要實(shí)現(xiàn)下列目標(biāo)： a. 要提出開發(fā)規(guī)范化的SRS提綱； b. 定義自己需要的具體的格式和內(nèi)容； c.產(chǎn)生附加的局部使用條款，如SRS質(zhì)量檢查清單或者SRS作者手冊等。3、軟件測試文檔編制規(guī)范軟件測試文檔編制規(guī)范 測試是軟件生存周期中一個獨(dú)立的、關(guān)鍵的階段，也是保證軟件質(zhì)量的重要手段。為了提高檢測出錯誤的幾率，使測試能有計劃地、有條不紊地進(jìn)行，就必須要編制測試文

6、檔。而標(biāo)準(zhǔn)化的測試文檔就如同一種通用的參照體系，可達(dá)到便于交流的目的。計算機(jī)軟件測試文檔編制規(guī)范的目的就是規(guī)定一組軟件測試文檔，定義每一種基本文檔的目的、格式和內(nèi)容。測試文檔中所規(guī)定的內(nèi)容可以作為對測試過程完備性的對照檢查表，這將會提高測試過程的每個階段的能見度，極大地提高測試工作的可管理性。 軟件測試文檔內(nèi)容 計算機(jī)軟件測試文檔編制規(guī)范主要定義了三種類型軟件測試文檔：測試計劃測試說明測試報告測試計劃 測試計劃描述測試活動的范圍、方法、資源和進(jìn)度。它規(guī)定被測試的項、被測試的特性、應(yīng)完成的測試任務(wù)、擔(dān)任各項工作的人員職責(zé)及與本計劃有關(guān)的風(fēng)險等測試說明 測試說明包括三個文檔： （1）測試設(shè)計說明詳

7、細(xì)描述測試方法，規(guī)定該設(shè)計及其有關(guān)測試所包括的特性(功能、性能、可移植性等)，還規(guī)定完成測試所需的測試用例和測試規(guī)程，并規(guī)定特性的通過準(zhǔn)則。（2）測試用例說明列出用于輸入的具體值以及預(yù)期的輸出結(jié)果，并規(guī)定在使用具體測試用例時，對測試規(guī)程的各種限制。將測試用例與測試設(shè)計分開，可以使它們用于多個設(shè)計并能在其它情形下重復(fù)使用。（3）測試規(guī)程說明規(guī)定對于運(yùn)行系統(tǒng)和執(zhí)行指定的測試用例來實(shí)現(xiàn)有關(guān)測試設(shè)計所要求的所有步驟。 測試報告 測試報告包括四類文檔： （1）測試項傳遞報告所謂的測試項是指作為測試對象的軟件項（源代碼、目標(biāo)代碼、作業(yè)控制代碼、數(shù)據(jù)等），該報告指明在開發(fā)組和測試組獨(dú)立工作的情況下或者在希望

8、正式開始測試的情況下為進(jìn)行測試而被傳遞的測試項。（2）測試日志測試組用于記錄測試執(zhí)行過程中發(fā)生的情況。（3）測試事件報告描述在測試執(zhí)行期間發(fā)生并需進(jìn)一步調(diào)查的一切事件。（4）測試總結(jié)報告總結(jié)與測試設(shè)計說明有關(guān)的測試活動。測試文檔的結(jié)構(gòu) 軟件測試文檔的內(nèi)容主要包括：測試計劃測試設(shè)計說明測試用例說明測試規(guī)程說明測試項傳遞報告測試日志測試事件報告以及測試總結(jié)報告1、測試計劃 1 測試計劃名稱 2 引言 3 測試項 4 被測試的特性 5 不被測試的特性 6 方法 7 項通過準(zhǔn)則 8 暫停標(biāo)準(zhǔn)和再啟動要求 9 應(yīng)提供的測試文件 10 測試任務(wù) 11 環(huán)境要求 12 職責(zé)13 人員和訓(xùn)練要求 14 進(jìn)度

9、15 風(fēng)險和應(yīng)急 16 批準(zhǔn) 2、測試設(shè)計說明 1 測試設(shè)計說明名稱 2 被測試的特性 3 方法詳述 4 測試用例名稱 5 特性通過準(zhǔn)則 1 測試用例說明名稱 2 測試項 3 輸入說明 4 輸出說明 5 環(huán)境要求 6 特殊的規(guī)程說明7 用例間的依賴關(guān)系 3、測試用例說明4、測試規(guī)程說明 5、測試項傳遞報告6、測試日志7、測試事件報告1 測試規(guī)程說明名稱 2 目的 3 特殊要求 4 規(guī)程步驟 1 傳遞報告名稱 2 傳遞項 3 位置 4 狀態(tài) 5 批準(zhǔn) 1 測試日志名稱 2 描述 3 活動和事件條目 1 測試事件報告名稱 2 摘要 3 事件描述 4 影響 8、測試總結(jié)報告 1 測試總結(jié)報告名稱2

10、簡述3 差異4 測試充分性評價5 結(jié)果概述6 評價7 活動總結(jié)8 批準(zhǔn)測試文檔的編制 軟件測試文檔的內(nèi)容主要包括測試計劃、測試設(shè)計說明、測試用例說明、測試規(guī)程說明、測試項傳遞報告、測試日志、測試事件報告以及測試總結(jié)報告八項內(nèi)容。需要強(qiáng)調(diào)，軟件測試包括對需求說明書的測試，因此，在軟件的需求分析階段，就應(yīng)開始測試文檔的編制工作，各種測試文檔的編寫應(yīng)按一定的格式進(jìn)行測試文檔的編制 1. 設(shè)計測試用例 測試用例（Test Case）是指對一項特定的軟件產(chǎn)品進(jìn)行測試任務(wù)的描述，體現(xiàn)測試方案、方法、技術(shù)和策略。內(nèi)容包括測試目標(biāo)、測試環(huán)境、輸入數(shù)據(jù)、測試步驟、預(yù)期結(jié)果、測試腳本等，并形成文檔2. 編寫測試文

11、檔 測試文檔主要由若干測試用例組成，各種測試文檔的編寫應(yīng)有文檔模板，按一定的格式進(jìn)行。 測試文檔由簡介和測試用例兩部分組成。簡介部分編制了測試目的、測試范圍、定義術(shù)語、參考文檔、概述等。測試用例部分逐一列示各測試用例。每個具體測試用例都將包括下列詳細(xì)信息：用例編號、用例名稱、測試等級、入口準(zhǔn)則、驗(yàn)證步驟、期望結(jié)果（含判斷標(biāo)準(zhǔn)）、出口準(zhǔn)則、注釋等。以上內(nèi)容涵蓋了測試用例的基本元素：測試索引，測試環(huán)境，測試輸入，測試操作，預(yù)期結(jié)果，評價標(biāo)準(zhǔn)。測試文檔的編制 實(shí)例 文件活動測試計劃測試設(shè)計說明測試用例說明測試規(guī)程說明測試項傳遞報告測試日志測試事件報告測試總結(jié)報告驗(yàn)收-安裝-系統(tǒng)子系統(tǒng)-模塊-4、軟件

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

13、件文檔的內(nèi)容和編排。浙江工業(yè)大學(xué)計算機(jī)學(xué)院 陸佳煒第四章 軟件文檔寫作要求軟件文檔寫作主要內(nèi)容軟件文檔的編寫原則 制定文檔的編寫策略 軟件文檔的質(zhì)量等級 制定文檔的編制計劃 建立文檔的編制規(guī)程 軟件文檔的質(zhì)量要求 軟件文檔的編寫技巧 確定軟件文檔類型的種類1、軟件文檔的編寫原則 軟件文檔的編寫原則 文檔編制的原則文檔編寫應(yīng)適應(yīng)文檔的讀者文檔編寫應(yīng)有必要的重復(fù)性文檔編寫應(yīng)具有一定靈活性文檔種類文檔詳細(xì)程度文檔的擴(kuò)展章節(jié)的擴(kuò)張與縮并程序設(shè)計的表現(xiàn)形式文檔的表現(xiàn)形式 文檔其他種類軟件文檔的編寫原則 文檔編制的原則文檔編寫應(yīng)適應(yīng)文檔的讀者文檔編寫應(yīng)有必要的重復(fù)性文檔編寫應(yīng)具有一定靈活性文檔種類文檔詳細(xì)

14、程度文檔的擴(kuò)展章節(jié)的擴(kuò)張與縮并程序設(shè)計的表現(xiàn)形式文檔的表現(xiàn)形式 文檔其他種類軟件文檔的編寫原則 根據(jù)一個項目的規(guī)模、復(fù)雜性和成敗風(fēng)險，決定應(yīng)編制的文檔種類及其詳細(xì)當(dāng)被開發(fā)的項目規(guī)模非常大時，可以將一個文檔拆分成多個卷進(jìn)行編制。項目開發(fā)計劃可能包括： 質(zhì)量保證計劃； 配置管理計劃； 用戶培訓(xùn)計劃； 安裝實(shí)施計劃。系統(tǒng)設(shè)計說明書可分寫成： 系統(tǒng)設(shè)計說明書； 子系統(tǒng)設(shè)計說明書。程序設(shè)計說明書可分寫成： 程序設(shè)計說明書； 接口設(shè)計說明書； 版本說明。 軟件文檔的編寫原則 所有的章節(jié)都可以進(jìn)一步細(xì)分或縮并，以適應(yīng)實(shí)際需要。程序的設(shè)計表現(xiàn)形式可以使用多種形式，如流程圖、判定表、等其他表現(xiàn)形式。按規(guī)定：重量

15、不超過30公斤的行李可免費(fèi)托運(yùn)。重量超過30公斤時，對超運(yùn)部分，頭等艙國內(nèi)乘客收4元/公斤；其它艙位國內(nèi)乘客收6元/公斤；外國乘客收費(fèi)為國內(nèi)乘客的2倍；殘疾乘客的收費(fèi)為正常乘客的1/2。 軟件文檔的編寫原則 2、制定文檔的編寫策略 制定文檔的編寫策略 文檔策略是由上級（資深）管理者提出并支持的，對下級開發(fā)單位或開發(fā)人員提供指導(dǎo)。策略規(guī)定主要的方向，而不是規(guī)定做什么或如何做。 文檔需要覆蓋整個軟件生存期 文檔應(yīng)是可管理的文檔應(yīng)適合于它的讀者文檔效應(yīng)應(yīng)貫穿到軟件的整個開發(fā)過程中文檔標(biāo)準(zhǔn)應(yīng)被標(biāo)識和使用 應(yīng)規(guī)定支持工具文檔策略制定文檔的編寫策略 評估現(xiàn)有策略條款的有效性和完整性的文檔檢查表適當(dāng)?shù)奈臋n的

16、決策作出了嗎？涉及文檔的策略聲明發(fā)布了嗎？負(fù)責(zé)開發(fā)文檔和產(chǎn)品文檔編寫工作的人員或部門落實(shí)了嗎？用于文檔編制的資源落實(shí)了嗎？負(fù)責(zé)文檔質(zhì)量的人員或部門落實(shí)了嗎？各管理層次和組織各分支之間的各種關(guān)系確定了嗎？對于文檔的編制、分發(fā)和維護(hù)等方面是否確定了職責(zé)、所需活動和聯(lián)系途徑？所有的文檔要求已列入整個項目開發(fā)計劃表中了嗎？適用的文檔標(biāo)準(zhǔn)已確定了嗎？是否已考慮采用支持工具和自動化的文檔編制？ 3、軟件文檔的質(zhì)量等級 軟件文檔的質(zhì)量等級 是不是每個人編寫的文檔質(zhì)量都一樣？如何確定文檔的質(zhì)量？如何保證？評價文檔的質(zhì)量主要從兩個方面： 文檔的結(jié)構(gòu)：其質(zhì)量從各個組成部分的順序和總體安排的簡單性來測定。 文檔的內(nèi)

17、容：從文檔內(nèi)容的正確性、完整性和明確性來判斷。軟件文檔的質(zhì)量等級 文檔的質(zhì)量可以按文檔的形式和要求劃分為四級：（1）最低限度文檔（1級文檔）：1級文檔適合開發(fā)工作量低于一個人月的軟件。該文檔應(yīng)包含程序清單、開發(fā)記錄、測試數(shù)據(jù)和程序簡介。（2）內(nèi)部文檔（2級文檔）：2級文檔可用于在精心研究后被認(rèn)為沒有與其他用戶共享資源的專用程序。除1級文檔提供的信息外，2級文檔還包括程序清單內(nèi)足夠的注釋以幫助用戶安裝和使用程序。（3）工作文檔（3級文檔）：3級文檔適合于由同一單位內(nèi)若干人聯(lián)合開發(fā)的程序，或可被其他單位使用的程序。（4）正式文檔（4級文檔）：4級文檔適合那些要正式發(fā)行供普遍使用的軟件產(chǎn)品。關(guān)鍵性程

18、序或具有重復(fù)管理應(yīng)用性質(zhì)（如工資計算）的程序需要4級文檔。4級文檔遵守GB 8567的有關(guān)規(guī)定。 軟件文檔的質(zhì)量等級 質(zhì)量從第1級到第四級，需要的投入和資源逐級增加，質(zhì)量保證機(jī)構(gòu)必須處于適當(dāng)?shù)男姓匚灰员ＷC達(dá)到期望的質(zhì)量等級。 為了保證文檔的質(zhì)量，主要從一下幾個方面： 評審鑒定 責(zé)任到人 采用制作工具4、制定文檔的編制計劃制定文檔的編制計劃 一般包括以下幾方面內(nèi)容： 列出應(yīng)編制文檔的目錄；提示編制文檔應(yīng)參考的標(biāo)準(zhǔn)；指定文檔管理員；提供編制文檔所需要的條件，落實(shí)文檔編寫人員、所需經(jīng)費(fèi)以及編制工具等；明確保證文檔質(zhì)量的方法；繪制進(jìn)度表，以圖表形式列出在軟件生存期各階段應(yīng)產(chǎn)生的文檔、編制人員、編制日

19、期、完成日期、評審日期等。 文檔計劃主要指出未來的活動，每個文檔應(yīng)該達(dá)到的質(zhì)量等級等內(nèi)容。文檔計劃檢查表 文檔計劃檢查表如下：文檔計劃編制好了嗎？所需的文檔類型確定好了嗎？所需的內(nèi)容是否已列提綱并描述了？文檔標(biāo)準(zhǔn)確定了嗎？文檔標(biāo)準(zhǔn)制訂好了嗎？有關(guān)文檔編制、文檔管理員、備用的文檔存儲及文檔評審的職責(zé)分配好了嗎？質(zhì)量準(zhǔn)則建立了嗎？有關(guān)提交草稿概要、初稿、修訂稿、圖示的計劃表是否已建立？評審日期確定了嗎？一個認(rèn)可的周期確定了嗎？制作方法是否已選定并作出計劃了？ 5、建立文檔的編制規(guī)程 建立文檔的編制規(guī)程 文檔編制規(guī)程提出關(guān)于文檔的計劃、編制、評審、制作和分發(fā)的邏輯順序。這些規(guī)程內(nèi)含審批、質(zhì)量保證及若

20、干控制點(diǎn)，概述修改步驟、存儲和維護(hù)要求以及更新方法。 計劃制定文檔編寫文檔編號文檔評審文檔簽署 歸檔保管文檔維護(hù)編制規(guī)程建立文檔的編制規(guī)程 評審是提供軟件產(chǎn)品質(zhì)量的有效方法。評審的評審點(diǎn)有：需求評審、概要設(shè)計評審、詳細(xì)設(shè)計評審和驗(yàn)收。計劃制定文檔編寫文檔編號文檔評審文檔簽署 歸檔保管文檔維護(hù)編制規(guī)程建立文檔的編制規(guī)程 計劃制定文檔編寫文檔編號文檔評審文檔簽署 歸檔保管文檔維護(hù)編制規(guī)程編寫審核會簽標(biāo)準(zhǔn)化批準(zhǔn)6、軟件文檔的質(zhì)量要求軟件文檔的質(zhì)量要求 （1）針對性：分清讀者、適應(yīng)需要。（2）精確性：行文確切，避免多義。（3）清晰性：力求簡明，運(yùn)用圖表。（4）完整性：自稱體系，避免引用。（5）靈活性：大的擴(kuò)展，小的合并。（6）可追溯性：逐步擴(kuò)展，前后照應(yīng)。7、軟件文檔的編寫技巧軟件文檔的編寫技巧 1. 從技術(shù)角度進(jìn)行文檔的編寫和評價 2. 明確文檔編寫人員的責(zé)任 3. 讓