計算機軟件文檔編制規(guī)范1

1、計算機軟件文檔編制計算機軟件文檔編制規(guī)范規(guī)范中標(biāo)軟件公司中標(biāo)軟件公司周明德周明德5 5 文檔過程文檔過程5.1 5.1 概述概述 有兩種主要類型的標(biāo)準(zhǔn)： a. 產(chǎn)品標(biāo)準(zhǔn)，它規(guī)定產(chǎn)品的特征和功能需求； b. 過程標(biāo)準(zhǔn)，它規(guī)定開發(fā)產(chǎn)品的過程。 文檔標(biāo)準(zhǔn)就是一種過程標(biāo)準(zhǔn)。應(yīng)用程序和計算機軟件的復(fù)雜性日益增加，使得給使用計算機的用戶提供完整的、正確的和易懂的文檔的需要更加迫切。本標(biāo)準(zhǔn)通過規(guī)定影響軟件文檔的質(zhì)量的活動（做什么和由誰做），提供達到這些目的的工具。 文檔常常是關(guān)心在軟件已經(jīng)實現(xiàn)后做些什么。然而，為了質(zhì)量，軟件文檔編制應(yīng)作為整個軟件生產(chǎn)過程的一部分。過程計劃應(yīng)把文檔計劃包括在內(nèi)。本標(biāo)準(zhǔn)也給用戶

2、和客戶提供工具以保證文檔過程實施。 本標(biāo)準(zhǔn)的主要活動是建立開發(fā)文檔的廣泛計劃。這是必須的，因為有計劃，文檔編制的質(zhì)量會更好，過程的效率會更高。本標(biāo)準(zhǔn)也規(guī)定何種信息對于文檔管理者是可用的和誰做評審及誰生產(chǎn)文檔。 本標(biāo)準(zhǔn)遵循GB/T 85662001信息技術(shù) 軟件生存周期過程。為其開發(fā)過程和管理過程中的主要文檔規(guī)定了編制規(guī)范。 本標(biāo)準(zhǔn)是按文檔由專門的文檔管理人員和文本編寫人員的模式規(guī)定的。具體的項目可根據(jù)具體情況安排。 文檔過程的活動應(yīng)按圖51中的順序執(zhí)行。 其中，有兩個陰影框。在一個陰影框中的所有活動應(yīng)在下一個陰影框中的活動開始之前完成。在陰影框中的活動可以并行執(zhí)行。虛線指示可能的重復(fù)。 在文檔

3、的最小內(nèi)容已經(jīng)由需方規(guī)定的情況下，這宜由文檔管理者在文檔計劃開發(fā)期間納入總數(shù)中。5.2 5.2 源材料準(zhǔn)備源材料準(zhǔn)備 需方應(yīng)允許文檔管理者訪問以下內(nèi)容： a）所有有關(guān)的規(guī)格說明、記錄格式、屏幕和報告布局、CASE 工具輸出和文檔的準(zhǔn)備所需要的任何其他的信息； b）若可用，軟件的操作副本； c）軟件的分析員和程序員，以及及時和確切地解答由文檔開發(fā)人員提出的問題； d）若可能，訪問典型的用戶（為了做讀者分析和可用性測試）。 為了增加對產(chǎn)品和它的讀者的了解，對軟件開發(fā)人員的訪問是必要的但使這樣的訪間保持到最小是文檔管理者的責(zé)任。 不管文檔管理者是否是軟件的開發(fā)者，需方應(yīng)提供適用的標(biāo)準(zhǔn)、風(fēng)格和格式指南

4、和其他相關(guān)的材料（除非，通?？捎玫模?。文檔管理者應(yīng)分發(fā)這些材料至需要它的文檔開發(fā)人員。 保證需方交付給文檔管理者的所有材料，當(dāng)交付時，是完整的和正確的且在交付后保持是最新的，這是需方的責(zé)任。 需方保證，提供的材料沒有一個違反任何其他部門的知識產(chǎn)權(quán)。 文檔管理者應(yīng)采取所有有理由的步驟，以保證由需方提供的材料保持在很好的狀態(tài)，應(yīng)保證需方要求的信息安全并在文檔項目完成后，所有材料返回給需方。 在某些情況下，不是所有材料需要返回；這應(yīng)在合同中定義。在某些情況下，由需方傳送給文檔管理者的材料要求保持機密的和安全的。合同宜規(guī)定對于傳送給文檔管理者的材料，需方要求文檔管理者的機密和安全等級。5.3 5.3

5、文檔計劃文檔計劃5.3.1 概要 文檔管理者應(yīng)準(zhǔn)備一文檔計劃，此計劃規(guī)定在文檔創(chuàng)建中要執(zhí)行的工作。此文檔計劃應(yīng)經(jīng)需方正式同意，以預(yù)示它完全覆蓋了需方的要求。 文檔計劃應(yīng)正式地描述計劃的文檔的范圍和限制，以及重要的文檔分析和設(shè)計決定。也應(yīng)規(guī)定在文檔開發(fā)期間實現(xiàn)的過程和控制。 文檔計劃應(yīng)包括（但不限于）以下內(nèi)容： a）計劃的文檔的工作名稱、目的、范圍和限制。 b）文檔的預(yù)定的讀者，和使用的目的。 c）文檔內(nèi)容的草案表，帶有估計的頁數(shù)和其他媒體的等效細節(jié)。 d）交付：打印副本數(shù)，是否提供電子副本，磁盤和文件格式（包括軟件版本）和在何處交付。 e）版權(quán)的擁有者和任何其他所有權(quán)。 f）適當(dāng)處，包括每個文

6、檔的安全或機密級。 g）管理文檔開發(fā)過程的步驟和控制，包括存儲、檢索、后備、處理和質(zhì)量保證（若要求）。 h）所用的生產(chǎn)方法、工具和工具版本。 i）文檔開發(fā)人員所在的隊伍的結(jié)構(gòu)，任選地，包括隊伍選擇計劃。 j）項目依賴。 k）所要求的人時和成本。 l）項目資源需求，包括需方提供的信息和其他資源。 m）在軟件開發(fā)期間，軟件變更傳送信息給文檔管理者的方法。 n）文檔的變更控制和維護的計劃（任選）。 o）實現(xiàn)后評審的計劃（任選）。 p）顯示適當(dāng)?shù)睦锍瘫臅r間表，包括： 1）文檔計劃批準(zhǔn)； 2）每個草案的準(zhǔn)備、評審和改正； 3）可用性測試； 4）打印、裝訂和發(fā)布。 若適當(dāng)，這些活動的每一個對于文檔的每一

7、項應(yīng)重復(fù)。 文檔計劃宜在文檔的開發(fā)開始以前準(zhǔn)備與批準(zhǔn)，以保證所有部門同意目標(biāo)和所用的方法。批準(zhǔn)后，計劃宜盡可能廣泛地分發(fā)；分發(fā)宜包括所有文檔開發(fā)人員和可能包括需方人員及子合同方。5.3.2 文檔計劃控制 在正式同意后，文檔管理者應(yīng)控制文檔計劃和它的發(fā)布。文檔管理者應(yīng)保持一份文檔計劃副本的分發(fā)的清單。若以后文檔計劃變更了（得到文檔管理者和需方的同意），文檔管理者應(yīng)保證所有得到文檔計劃副本的人員，應(yīng)得到變更通知。 因為，計劃的過時的副本可能引起問題，文檔管理者宜禁止計劃的未控制的副本并制訂計劃的所有副本已經(jīng)更新的審核過程。5.4 5.4 文檔開發(fā)文檔開發(fā) 按文檔計劃規(guī)定進行文檔開發(fā)。通常，在進行文

8、檔開發(fā)前，要規(guī)定文檔的格式（風(fēng)格）。在軟件的開發(fā)和管理過程中需要那些文檔，每種文檔的規(guī)范在下面說明。5.5 5.5 評審評審5.5.1 概述 本節(jié)規(guī)定文檔評審的要求和相關(guān)活動。本節(jié)主要以用戶文檔的評審為例說明。對于開發(fā)文檔的評審，由供方組織和實施。而批準(zhǔn)由開發(fā)組織的上級技術(shù)機構(gòu)實施。更要著重經(jīng)常性的、非正式的注重實效的評審。不是要追求形式。 用戶文檔的評審應(yīng)由需方實現(xiàn)，包括當(dāng)需要時與文檔管理者討論。 l 評審的目的是保證提交的材料是完整的和正確的并滿足了在合同和文檔計劃中定義的需方的需要。 評審宜由合適的有資格的人員執(zhí)行，這些人員被授權(quán)請求變更和批準(zhǔn)文檔的內(nèi)容。 l 需方宜限止評審人員數(shù)為評審

9、功能所必需的那些。 需方在批準(zhǔn)每個用戶文檔草案之前，應(yīng)保證文檔的安全和合法。 為評審交付的文檔應(yīng)包括從文檔管理者來的說明書，說明評審的目的和評審員的職責(zé)。 注1：在需方和文檔管理者之間在整個開發(fā)過程期間維持良好的通信會提高文檔的質(zhì)量并利于評審成功。這宜包括非正式的討論和盡早地提供樣板或初始材料給需方。 注2：在要求的變更超出了合同和文檔計劃的范圍時，需要變更合同。 注3：評審過程不免除文檔管理者，他們的責(zé)任是試圖盡可能保證文檔的精確和完整。 注4：從評審的結(jié)果而來的需方的評論結(jié)果宜用或是加上標(biāo)記的草案或用有適當(dāng)?shù)膮⒖嫉姆绞綄懺u論。需方宜保持變更的副本為了與下一草案相比較。評論應(yīng)使文檔開發(fā)人員能

10、實現(xiàn)所要求的變更而不需要評審人員的進一步解釋。 注5：對于大的、復(fù)雜的系統(tǒng)或正在寫文檔時系統(tǒng)仍在開發(fā)，可能需要多于兩次草案和一次校樣。在這樣情況下，最多的草案數(shù)宜在需方和文檔管理者之間同意并在文檔計劃中規(guī)定。5.5.2 文檔計劃評審 此評審的目的應(yīng)保證文檔計劃定義的文檔，當(dāng)完成時，既滿足開發(fā)過程的需要也滿足需方在合同中規(guī)定的的文檔目標(biāo)。需方同意文檔計劃，是同意在計劃中定義的用戶文檔的所有可交付的特征。 注：需方宜放注意至在內(nèi)容的草案表中展示的文檔的結(jié)構(gòu)、完整性和可用性。只要適當(dāng)，文檔計劃宜在第一個草案開始工作之前評審和批準(zhǔn)。5.5.3 第一個草案評審 第一個草案應(yīng)包含如在文檔計劃中描述的文檔體

11、，加上內(nèi)容表，附錄和詞匯。在使用自動索引工具處，生成的索引包含位置參照。標(biāo)點符號、風(fēng)格和版面應(yīng)如在文檔計劃中描述的。 文檔的第一個草案的評審目的是核查文檔的技術(shù)正確性和完整性，以保證草案滿足文檔計劃的目標(biāo)。標(biāo)點符號、風(fēng)格和版面應(yīng)如在文檔計劃中定義的。 在批準(zhǔn)第一個草案中，除了要求的變更外，評審批準(zhǔn)技術(shù)正確性、結(jié)構(gòu)清楚性和文檔的完整性。 注1：第一個草案宜在交付前編輯。這有兩個理由： a）這保證評審者不分心于改正印刷的和版面的錯誤； b）保證由編輯過程引起的任何技術(shù)錯誤被評審者捕獲。 注2：草案應(yīng)針對在文檔計劃中批準(zhǔn)的目標(biāo)、讀者定義、內(nèi)容表和其他特征進行評審。在帶有評論的第一個草案返回前，宜確認(rèn)

12、，若草案完全改正了，將滿足文檔計劃的要求。5.5.4 第二個草案評審 第二個草案應(yīng)包在第一個草案評審中同意的所有變更且應(yīng)以盡可能接近最后的形式包括在文檔計劃中定義的可交付的內(nèi)容。 此評審的目的是核查在第一個草案中的內(nèi)容已經(jīng)正確實現(xiàn)。 在第二個草案的批準(zhǔn)中，除了草案的物理形式外，批準(zhǔn)文檔的所有方面。草案的物理形式可能與可交付的不精確相同。 注：在批準(zhǔn)第二個草案前，宜確認(rèn)草案（包含評審對草案的評論）已經(jīng)準(zhǔn)備好批準(zhǔn)。5.5.5 校樣評審 校樣應(yīng)包括在第二個草案評審中同意的所有變更。 此評審的目的是核查對第二個草案的評論已正確實現(xiàn)。任何不正確實現(xiàn)的評論應(yīng)迅速地通知文檔管理者，他們應(yīng)相應(yīng)地修改文檔并返回

13、可替換部分的副本，用于進一步評審。 由批準(zhǔn)證明，被接受的文檔已準(zhǔn)備好生產(chǎn)。5.6 5.6 與其他公司的文檔開發(fā)子與其他公司的文檔開發(fā)子合同合同 文檔管理者應(yīng)保證子合同的文檔遵循本標(biāo)準(zhǔn)，遵循文檔計劃和合同。 在子合同的文檔中，文檔管理者作為本標(biāo)準(zhǔn)的需方而子合同承擔(dān)者作為文檔管理者。 注：文檔管理者應(yīng)與子合同承擔(dān)者有規(guī)定本標(biāo)準(zhǔn)的協(xié)議。6 6 文檔編制要求文檔編制要求6.1 6.1 軟件生存周期與各種文檔軟件生存周期與各種文檔的編制的編制 在計算機軟件的生存周期中，一般地說，應(yīng)該產(chǎn)生以下一些基本文檔。 可行性分析（研究）報告； 軟件（或項目）開發(fā)計劃； 軟件需求規(guī)格說明； 接口需求規(guī)格說明； 系統(tǒng)子

14、系統(tǒng)設(shè)計（結(jié)構(gòu)設(shè)計）說明； 軟件（結(jié)構(gòu)）設(shè)計說明； 接口設(shè)計說明； 數(shù)據(jù)庫（頂層）設(shè)計說明； （軟件）用戶手冊； 操作手冊； 測試計劃； 測試報告； 軟件配置管理計劃； 軟件質(zhì)量保證計劃； 開發(fā)進度月報； 項目開發(fā)總結(jié)報告； 軟件產(chǎn)品規(guī)格說明； 軟件版本說明等。 本標(biāo)準(zhǔn)將給出這些文檔的編制規(guī)范，同時，本標(biāo)準(zhǔn)也是這些文檔的編寫質(zhì)量的檢驗準(zhǔn)則。一般地說，一個軟件總是一個計算機系統(tǒng)（包括硬件，固件和軟件）的組成部分。鑒于計算機系統(tǒng)的多樣性，本標(biāo)準(zhǔn)一般不涉及整個系統(tǒng)開發(fā)中的文檔編制問題，本標(biāo)準(zhǔn)僅僅是軟件開發(fā)過程中的文檔編制指南。 對于使用文檔的人員而言他們所關(guān)心的文件的種類隨他們所承擔(dān)的工作而異。 管

15、理人員： 可行性分析（研究）報告， 項目開發(fā)計劃， 軟件配置管理計劃， 軟件質(zhì)量保證計劃， 開發(fā)進度月報， 項目開發(fā)總結(jié)報告； 開發(fā)人員： 可行性分析（研究）報告， 項目開發(fā)計劃， 軟件需求規(guī)格說明， 接口需求規(guī)格說明， 軟件（結(jié)構(gòu)）設(shè)計說明， 接口設(shè)計說明書， 數(shù)據(jù)庫（頂層）設(shè)計說明， 測試計劃， 測試報告； 維護人員： 軟件需求規(guī)格說明， 接口需求規(guī)格說明， 軟件（結(jié)構(gòu)）設(shè)計說明， 測試報告， 用 戶： 軟件產(chǎn)品規(guī)格說明， 軟件版本說明， 用戶手冊， 操作手冊。 本標(biāo)準(zhǔn)規(guī)定了在軟件開發(fā)過程中文檔編制的要求，這些文檔從使用的角度可分為用戶文檔和開發(fā)文檔兩大類。其中，用戶文檔必須交給用戶。用戶

16、應(yīng)該得到的文檔的種類和規(guī)模由供應(yīng)者與用戶之間簽訂的合同規(guī)定。 如前所述，軟件，從出現(xiàn)一個構(gòu)思之日起，經(jīng)過軟件開發(fā)成功投入使用，直到最后決定停止使用并被另一項軟件代替之時止，被認(rèn)為是該軟件的一個生存周期，一般地說這個軟件生存周期可以分成以下六個階段： 可行性與計劃研究階段； 需求分析階段； 設(shè)計階段； 實現(xiàn)階段； 測試階段； 運行與維護階段。 在可行性分析（研究）與計劃階段內(nèi)，要確定該軟件的開發(fā)目標(biāo)和總的要求，要進行可行性分析、投資收益分析、制訂開發(fā)計劃，并完成應(yīng)編制的文檔。 在需求分析階段內(nèi)，由系統(tǒng)分析人員對被設(shè)計的系統(tǒng)進行系統(tǒng)分析，確定對該軟件的各項功能、性能需求和設(shè)計約束，確定對文檔編制的

17、要求，作為本階段工作的結(jié)果，一般地說軟件需求規(guī)格說明（也稱為：軟件需求說明、軟件規(guī)格說明）、數(shù)據(jù)要求說明和初步的用戶手冊應(yīng)該編寫出來。 在設(shè)計階段內(nèi)，系統(tǒng)設(shè)計人員和程序設(shè)計人員應(yīng)該在反復(fù)理解軟件需求的基礎(chǔ)上，提出多個設(shè)計，分析每個設(shè)計能履行的功能并進行相互比較，最后確定一個設(shè)計，包括該軟件的結(jié)構(gòu)、模塊（或CSCI）的劃分、功能的分配，以及處理流程。在被設(shè)計系統(tǒng)比較復(fù)雜的情況下，設(shè)計階段應(yīng)分解成概要設(shè)計階段和詳細設(shè)計階段兩個步驟。在一般情況下，應(yīng)完成的文檔包括：結(jié)構(gòu)設(shè)計說明、詳細設(shè)計說明和測試計劃初稿。 在實現(xiàn)階段內(nèi)，要完成源程序的編碼、編譯（或匯編）和排錯調(diào)試得到無語法錯的程序清單，要開始編寫

18、進度日報、周報和月報（是否要有日報或周報，取決于項目的重要性和規(guī)模），并且要完成用戶手冊、操作手冊等面向用戶的文檔的編寫工作，還要完成測試計劃的編制。 在測試階段：該程序?qū)⒈蝗娴販y試，已編制的文檔將被檢查審閱。一般要完成測試分析報告。作為開發(fā)工作的結(jié)束，所生產(chǎn)的程序、文檔以及開發(fā)工作本身將逐項被評價，最后寫出項目開發(fā)總結(jié)報告。 在整個開發(fā)過程中（即前五個階段中），開發(fā)集體要按月編寫開發(fā)進度月報。 在運行和維護階段，軟件將在運行使用中不斷地被維護，根據(jù)新提出的需求進行必要而且可能的擴充和刪改、更新和升級。6.2 6.2 文檔編制中的考慮因素文檔編制中的考慮因素 文檔編制是開發(fā)過程的有機組成部分

19、，也是一個不斷努力的工作過程。是一個從形成最初輪廓、經(jīng)反復(fù)檢查和修改，直至程序和文檔正式交付使用的完整過程。其中每一步都要求工作人員做出很大努力。要保證文檔編制的質(zhì)量，要體現(xiàn)每個開發(fā)項目的特點，也要注意不要花太多的人力。為此編制中要考慮如下各項因素。6.2.1 文檔的讀者 每一種文檔都具有特定的讀者。這些讀者包括個人或小組、軟件開發(fā)單位的成員或社會上的公眾、從事軟件工作的技術(shù)人員、管理人員或領(lǐng)導(dǎo)干部。他們期待著使用這些文檔的內(nèi)容來進行工作，例如設(shè)計、編寫程序、測試、使用、維護或進行計劃管理。因此這些文檔的作者必須了解自己的讀者。這些文檔的編寫必須注意適應(yīng)自己的特定讀者的水平、特點和要求。6.2

20、.2 重復(fù)性 本規(guī)范中列出的文檔編制規(guī)范的內(nèi)容要求中，顯然存在某些重復(fù)。較明顯的重復(fù)有兩類。引言是每一種文檔都要包含的內(nèi)容，以向讀者提供總的梗概.第二類明顯的重復(fù)是各種文檔中的說明部分，如對功能性能的說明；對輸入、輸出的描述；系統(tǒng)中包含的設(shè)備等。這是為了方便每種文檔各自的讀者，每種文檔應(yīng)該自成體系，盡量避免讀一種文檔時又不得不去參考另一種文檔。當(dāng)然，在每一種文檔里，有關(guān)引言、說明等同其他文檔相重復(fù)的部分，在行文上、在所用的術(shù)語上、在詳細的程度上，還是應(yīng)該有一些差別以適應(yīng)各種文檔的不同讀者的需要。6.2.3 靈活性 鑒于軟件開發(fā)是具有創(chuàng)造性的腦力勞動，也鑒于不同軟件在規(guī)模上和復(fù)雜程度上差別極大，

21、本規(guī)范認(rèn)為在文檔編制工作中應(yīng)允許一定的靈活性。這種靈活性表現(xiàn)在如下各款。 a. 應(yīng)編制的文檔種類 盡管本規(guī)范認(rèn)為在一般情況下，一項軟件的開發(fā)過程中，應(yīng)產(chǎn)生如上所述的各種文檔，然而針對一項具體的軟件開發(fā)項目，有時不必編制這么多的文檔，可以把幾種文檔合并成一種。一般地說，當(dāng)項目的規(guī)模、復(fù)雜性和失敗風(fēng)險增大時，文檔編制的范圍，管理手續(xù)和詳細程度將隨之增加，反之，則可適當(dāng)減少。為了恰當(dāng)?shù)卣莆者@種靈活性，本規(guī)范要求貫徹分工負(fù)責(zé)的原則，這意味著： 1） 一個軟件開發(fā)單位的領(lǐng)導(dǎo)機構(gòu)應(yīng)該根據(jù)本單位經(jīng)營承包的應(yīng)用軟件的專業(yè)領(lǐng)域和本單位的管理能力，制定一個對文檔編制要求的實施規(guī)定，主要是：在不同的條件下，應(yīng)該形成

22、哪些文檔？這些文檔的詳細程度？該開發(fā)單位的每一個項目負(fù)責(zé)人，必須認(rèn)真執(zhí)行這個實施規(guī)定。 2） 對于一個具體的應(yīng)用軟件項目，項目負(fù)責(zé)人應(yīng)根據(jù)上述實施規(guī)定，確定一個文檔編制計劃（可以包含在軟件開發(fā)計劃中），其中包括： （1） 應(yīng)該編制哪幾種文檔，詳細程度如何？ (2) 各個文檔的編制負(fù)責(zé)人和進度要求； (3) 審查、批準(zhǔn)的負(fù)責(zé)人和時間進度安排； (4) 在開發(fā)時間內(nèi)，各文檔的維護、修改和管理的負(fù)責(zé)人，以及批準(zhǔn)手續(xù)。 每項工作必須落實到人。 這個文件編制計劃是整個開發(fā)計劃的重要組成部份。 3） 有關(guān)的設(shè)計人員則必須嚴(yán)格執(zhí)行這個文檔編制計劃。 b. 文檔的詳細程度 從同一份提綱起草的文件的篇幅大小往往不同，可以少到幾頁，也可以長達幾百頁。對于這種差別，本規(guī)范是允許的。此詳細程