軟件文檔管理指南

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

2、過在本標準中引用而構成為本標準的條文。本標準出版時，所示版本均為有效，所有標準都會被修訂，使用本標準的各方應探討使用下列標準最新版本的可能性。計算機軟件開發(fā)規(guī)范計算機軟件產(chǎn)品開發(fā)文件編制指南軟件工程術語定義本標準采用下列定義，其他定義見。文檔一種數(shù)據(jù)媒體和其上所記錄的數(shù)據(jù)。 它具有永久性并可以由人或機器閱讀。 通常僅用于描述人工可讀的內容。例如，技術文件、設計文件、版本說明文件。文檔（集）；文檔編制一個或多個相關文檔的集合。文檔計劃一個描述文檔編制工作方法的管理用文檔。該計劃主要描述要編制什么類型的文檔，這些文檔的內容是什么，何時編寫，由誰編寫，如何編寫，以及什么是影響期望結果的可用資源和外界

3、因素。文檔等級對所需文檔的一個說明， 它指出文檔的范圍、 內容、格式及質量， 可以根據(jù)項目、 費用、預期用途、作用范圍或其他因素選擇文檔等級。軟件產(chǎn)品軟件開發(fā)過程的結果，并推出供用戶使用的軟件實體。軟件文檔的作用) 管理依據(jù)；) 任務之間聯(lián)系的憑證；) 質量保證；) 培訓與參考；) 軟件維護支持；) 歷史檔案。管理依據(jù)在軟件開過過程中， 管理者必須了解開發(fā)進度、 存在的問題和預期目標。 每一階段計劃安排的定期報告提供了項目的可見性。 定期報告還提醒各級管理者注意該部門對項目承擔的責任以及該部門效率的重要性。 開發(fā)文檔規(guī)定若干個檢查點和進度表， 使管理者可以評定項目的進度，如果開發(fā)文檔有遺漏，不

4、完善，或內容陳舊，則管理者將失去跟蹤和控制項目的重要依據(jù)。任務之間聯(lián)系的憑證大多數(shù)軟件開發(fā)項目通常被劃分成若干個任務，并由不同的小組去完成。學科方面的專家建立項目， 分析員闡述系統(tǒng)需求，設計員為程序員制定總體設計，程序員編制詳細的程序代碼，質量保證專家和審查員評價整個系統(tǒng)性能和功能的完整性，負責維護的程序員改進各種操作或增強某些功能。這些人員需要的互相聯(lián)系是通過文檔資料的復制、分發(fā)和引用而實現(xiàn)的，因而，任務之間的聯(lián)系是文檔的一個重要功能。大多數(shù)系統(tǒng)開發(fā)方法為任務的聯(lián)系規(guī)定了一些正式文檔。分析員向設計員提供正式需求規(guī)格說明，設計員向程序員提供正式設計規(guī)格說明，等等。質量保證那些負責軟件質量保證和

5、評估系統(tǒng)性能的人員需要程序規(guī)格說明、測試和評估計劃、 測試該系統(tǒng)用的各種質量標準以及關于期望系統(tǒng)完成什么功能和系統(tǒng)怎樣實現(xiàn)這些功能的清晰說明；必須制訂測試計劃和測試規(guī)程，并報告測試結果；他們還必須說明和評估完全、控制、計算、 檢驗例行程序及其他控制技術。這些文檔的提供可滿足質量保證人員和審查人員上述工作的需要。培訓與參考軟件文檔的另一個功能是使系統(tǒng)管理員、操作員、 用戶、 管理者和其他有關人員了解系統(tǒng)如何工作，以及為了達到他們的各自的目的，如何使用系統(tǒng)。軟件維護支持維護人員需要軟件系統(tǒng)的詳細說明以幫助他們熟悉系統(tǒng)，找出并修正錯誤， 改進系統(tǒng)以適應用戶需求的變化或適應系統(tǒng)環(huán)境的變化。歷史檔案軟件

6、文檔可用作未來項目的一種資源。通常文檔記載系統(tǒng)的開發(fā)歷史，可使有關系統(tǒng)結構的基本思想為以后的項目利用。系統(tǒng)開發(fā)人員通過審閱以前的系統(tǒng)以查明什么部分已實驗過了， 什么部分運行得很好，什么部分因某種原因難以運行而被排除。良好的系統(tǒng)文檔有助于把程序移植和轉移到各種新的系統(tǒng)環(huán)境中。管理者的作用管理者嚴格要求軟件開發(fā)人員和編制組完成文檔編制，并且在策略、標準、規(guī)程、資源分配和編制計劃方面給予支持。)管理者對文檔工作的責任。管理者要認識到正式或非正式文檔都是重要的，還要認識到文檔工作必須包括文檔計劃、編寫、修改、形成、分發(fā)和維護等各個方面。)管理者對文檔工作的支持。管理者應為編寫文檔的人員提供指導和實際鼓

7、勵，并使各種資源有效地用于文檔開發(fā)。) 管理者的主要職責：） 建立編制、登記、出版系統(tǒng)文檔和軟件文檔的各種策略；） 把文檔計劃作為整個開發(fā)工作的一個組成部分；） 建立確定文檔質量、測試質量和評審質量的各種方法的規(guī)程；） 為文檔的各個方面確定和準備各種標準和指南；） 積極支持文檔工作以形成在開發(fā)工作中自覺編制文檔的團隊風氣；） 不斷檢查已建立起來的過程，以保證符合策略和各種規(guī)程并遵守有關標準和指南。通常，項目管理者在項目開發(fā)前應決定如下事項：要求哪些類型的文檔；提供多少種文檔；文檔包含的內容；達到何種級別的質量水平；何時產(chǎn)生何種文檔；如何保存、維護文檔以及如何進行通信。如果一個軟件合同是有效的，

8、 應要求文檔滿足所接受的標準， 并規(guī)定所提供的文檔類型、每種文檔的質量水平以及評審和通過的規(guī)程。制訂文檔編制策略文檔策略是由上級 （資深） 管理者新任務并支持的， 對下級開發(fā)單位或開發(fā)人員提供指導。策略規(guī)定主要的方向不是做什么或如何做的詳細說明。一般說來， 文檔編制策略陳述要明確， 并通告到每個人且理解它， 進而使策略被他們貫徹實施。支持有效文檔策略的基本條件：) 文檔需要覆蓋整個軟件生存期在項目早期幾個階段就要求有文檔， 而且在貫穿軟件開發(fā)過程中必須是可用的和可維護的。在開發(fā)完成后，文檔應滿足軟件的使用、維護、增強、轉換或傳輸。) 文檔應是可管理的指導和控制文檔的獲得維護，管理者和發(fā)行專家應

9、準備文檔產(chǎn)品、進度、可靠性、 資源，質量保證和評審規(guī)程的詳細計劃大綱。) 文檔應適合于它的讀者讀者可能是管理者、分析員、無計算機經(jīng)驗的專業(yè)人員、維護人員、文書人員等。根據(jù)任務的執(zhí)行， 他們要求不同的材料表示和不同的詳細程度。 針對不同的讀者， 發(fā)行專家應負責設計不同類型的文檔。) 文檔效應應貫穿到軟件的整個開發(fā)過程中在軟件開發(fā)的整個過程中，應充分體現(xiàn)文檔的作用和限制，即文檔應指導全部開發(fā)過程。) 文檔標準應被標識和使用應盡可能地采納現(xiàn)行的標準，若沒有合適的現(xiàn)行標準，必要時應研制適用的標準或指南。)應規(guī)定支持工具工具有助于開發(fā)和維護軟件產(chǎn)品，包括文檔。 因此盡可能地使用工具是經(jīng)濟的、附錄中的檢查

10、表為制定策略條款或評估現(xiàn)有策略條款的有效性和完整性提供幫助。可行的。制訂文檔編制標準和指南在一個機構內部，應采用一些標準和指南：軟件生存期模型；文檔類型和相互關系；文檔質量。這些標準和指南決定如何實現(xiàn)文檔任務，將提供一些準則以評價機構內所產(chǎn)生的軟件文檔的完整性、可用性和適合性。盡可能地采用現(xiàn)行的國家和國際標準，若現(xiàn)行的標準不適用，機構應制訂自己的標準。選擇軟件生存期模型現(xiàn)有的一些軟件生存期模型，對于不同的階段有不同的詞匯，從軟件文檔的觀點來看，采用哪種模型都無關緊要， 只要階段和相應的文檔是清晰定義的、 已計劃的， 并且對于任何具體軟件項目是能遵循的。 因此，管理者應選擇一個軟件生存期模型并保

11、證該模型在他們機構內是適用的。管理者將會發(fā)現(xiàn)所進行的階段和相應任務的定義有助于監(jiān)控軟件項目的進展。相應于特定階段生成的文檔可用作該階段的評審、通過和完成的檢驗點，而這種檢驗應在下一階段開始前進行。規(guī)定文檔類型和內容下面給出軟件文檔主要類型的大綱，這個大綱不是詳盡的或最后的，但適合作為主要類型軟件文檔的檢驗表。而管理者應規(guī)定何時定義他們的標準文檔類型。軟件文檔歸入如下三種類別：) 開發(fā)文檔描述開發(fā)過程本身；) 產(chǎn)品文檔描述開發(fā)過程的產(chǎn)物；) 管理文檔記錄項目管理的信息。開發(fā)文檔開發(fā)文檔是描述軟件開發(fā)過程，包括軟件需求、軟件設計、軟件測試、保證軟件質量的一類文檔，開發(fā)文檔也包括軟件的詳細技術描述（

12、程序邏輯、程序間相互關系、數(shù)據(jù)格式和存儲等）。開發(fā)文檔起到如下五種作用：) 它們是軟件開發(fā)過程中包含的所有階段之間的通信工具，它們記錄生成軟件需求、設計、編碼和測試的詳細規(guī)定和說明；) 它們描述開發(fā)小組的職責。通過規(guī)定軟件、主題事項、文檔編制、質量保證人員以及包含在開發(fā)過程中任何其他事項的角色來定義做直截了當、如何做和何時做；) 它們用作檢驗點而允許管理者評定開發(fā)進度。如果開發(fā)文檔丟失、不完整或過時，管理者將失去跟蹤和控制軟件項目的一個重要工具；) 它們形成了維護人員所要求的基本的軟件支持文檔。而這些支持文檔可作為產(chǎn)品文檔的一部分；) 它們記錄軟件開發(fā)的歷史?；镜拈_發(fā)文檔是：可行性研究和項目

13、任務書；需求規(guī)格說明；功能規(guī)格說明；設計規(guī)格說明，包括程序和數(shù)據(jù)規(guī)格說明；開發(fā)計劃；軟件集成和測試計劃；質量保證計劃、標準、進度；安全和測試信息。產(chǎn)品文檔產(chǎn)品文檔規(guī)定關于軟件產(chǎn)品的使用、維護、增強、轉換和傳輸?shù)男畔?。產(chǎn)品的文檔起到如下三種作用：) 為使用和運行軟件產(chǎn)品的任何人規(guī)定培訓和參考信息；) 使得那些未參加開發(fā)本軟件的程序員維護它；) 促進軟件產(chǎn)品的市場流通或提高可接受性。產(chǎn)品文檔用于下列類型的讀者：用戶 他們利用軟件輸入數(shù)據(jù)、檢索信息和解決問題；運行者 他們在計算機系統(tǒng)上運行軟件；維護人員 他們維護、增強或變更軟件。產(chǎn)品文檔包括如下內容：用于管理者的指南和資料，他們監(jiān)督軟件的使用；宣傳

14、資料通告軟件產(chǎn)品的可用性并詳細說明它的功能、運行環(huán)境等；一般信息對任何有興趣的人描述軟件產(chǎn)品?；镜漠a(chǎn)品文檔包括：培訓手冊；參考手冊和用戶指南；軟件支持手冊；產(chǎn)品手冊和信息廣告。管理文檔這種文檔建立在項目管理信息的基礎上，諸如：開發(fā)過程的每個階段的進度和進度變更的記錄；軟件變更情況的記錄；相對于開發(fā)的判定記錄；職責定義。這種文檔從管理的角度規(guī)定涉及軟件生存的信息。相關文檔的詳細規(guī)定和編寫格式見。確定文檔的質量等級僅僅依據(jù)規(guī)章、 傳統(tǒng)的做法或合同的要求去制作文檔是不夠的。 管理者還必須確定文檔的質量要求以及如何達到和保證質量要求。質量要求的確定取決于可得到的資源、 項目的大小和風險， 可以對該產(chǎn)

15、品的每個文檔的格式及詳細程度作出明確的規(guī)定。每個文檔的質量必須在文檔計劃期間就有明確的規(guī)定。 文檔的質量可以按文檔的形式和列出的要墳劃分為四級。最低限度文檔（級文檔） 級文檔適合開發(fā)工作量低于一個人月的開發(fā)者自用程序。該文檔應包含程序清單、開發(fā)記錄、測試數(shù)據(jù)和程序簡介。內部文檔（級文檔） 級文檔可用于在精心研究后被認為似乎沒有與其他用戶共享資源的專用程序。 除級文檔提供的信息外， 級文檔還包括程序清單內足夠的注釋以幫助用戶安裝和使用程序。工作文檔（級文檔）級文檔適合于由同一單位內若干人聯(lián)合開發(fā)的程序，或可被其他單位使用的程序。正式文檔（級文檔）級文檔適合那些要正式發(fā)行供普遍使用的軟件產(chǎn)品。關鍵

16、性程序或具有重復管理應用性質（如工資計算）的程序需要級文檔。級文檔遵守的有關規(guī)定。質量方面需要考慮的問題即要包含文檔的結構，也要包含文檔的內容。文檔內容可以根據(jù)正確性、 完整性和明確性來判斷。而文檔結構由各個組成部分的順序和總體安排的簡單性來測定。 要達到這四個質量等級，需要的投入和資源逐級增加，質量保證機構必須處于適當?shù)男姓匚灰员ＷC達到期望的質量等級。文檔編制計劃文檔計劃可以是整個項目計劃的一部分或是一個獨立的文檔。 應該編寫文檔計劃并把它分發(fā)給全體開發(fā)組成員，作為文檔重要性的具體依據(jù)和管理部門文檔工作責任的備忘錄。對于小的、非正式的項目，文檔計劃可能只有一頁紙；對于較大的項目，文檔計劃可能是一個綜合性的正式文檔，這樣的文檔計劃應遵循各項嚴格的標準及正規(guī)的評審和批準過程。編制計劃的工作應及早開始， 對計劃的評審應貫穿項目的全過程。 如同任何別的計劃一樣，文檔計劃指出未來的各項活動， 當需要修改時必須加以修改。 導致對計劃作適當修改的常規(guī)評審應作為該項目工作的一部分，所有與該計劃有關的人員都應得到文檔計劃。文檔計劃一般包括以下幾方面內容：) 列出應編制文檔的目錄；) 提示編制文檔應參考的標準；)