軟件文檔管理指南

領測軟件測試網 1 范圍     本標準為那些對軟件或基于軟件的產品的開發負有職責的管理者提供軟件文檔的管理指南。本標準的目的在于協助管理者在他們的機構中產生有效的文檔。

    本標準涉及策略、標準、規程、資源和計劃，管理者必須關注這些內容，以便有效地管理軟件文檔。

    本標準期望應用于各種類型的軟件，從簡單的程序到復雜的軟件系統。并期望覆蓋各種類型的軟件文檔，作用于軟件生存期的各個階段。

    不論項目的大小，軟件文檔管理的原則是一致的。對于小項目，可以不采用本標準中規定的有關細節。管理者可剪裁這些內容以滿足他們的特殊需要。

    本標準是針對文檔編制管理而提出的，不涉及軟件文檔的內容和編排。

    2 引用標準

    下列標準所包含的條文，通過在本標準中引用而構成為本標準的條文。本標準出版時，所示版本均為有效，所有標準都會被修訂，使用本標準的各方應探討使用下列標準最新版本的可能性。

    GB 8566-88 計算機軟件開發規范

    GB 8567-88 計算機軟件產品開發文件編制指南

    GB/T 11457-1995 軟件工程術語

    3 定義

    本標準采用下列定義，其他定義見 GB/T 11457 。

    3.1 文檔 document

    一種數據媒體和其上所記錄的數據。它具有永久性并可以由人或機器閱讀。通常僅用于描述人工可讀的內容。例如，技術文件、設計文件、版本說明文件。

    3.2 文檔（集）；文檔編制 documentation

    一個或多個相關文檔的集合。

    3.3 文檔計劃 documentation plan

    一個描述文檔編制工作方法的管理用文檔。該計劃主要描述要編制什么類型的文檔，這些文檔的內容是什么，何時編寫，由誰編寫，如何編寫，以及什么是影響期望結果的可用資源和外界因素。

    3.4 文檔等級 level of documentation

    對所需文檔的一個說明，它指出文檔的范圍、內容、格式及質量，可以根據項目、費用、預期用途、作用范圍或其他因素選擇文檔等級。

    3.5 軟件產品 software product

    軟件開發過程的結果，并推出供用戶使用的軟件實體。

    4 軟件文檔的作用

    a) 管理依據；

    b) 任務之間聯系的憑證；

    c) 質量保證；

    d) 培訓與參考；

    e) 軟件維護支持；

    f) 歷史檔案。

    4.1 管理依據

    在軟件開過過程中，管理者必須了解開發進度、存在的問題和預期目標。每一階段計劃安排的定期報告提供了項目的可見性。定期報告還提醒各級管理者注意該部門對項目承擔的責任以及該部門效率的重要性。開發文檔規定若干個檢查點和進度表，使管理者可以評定項目的進度，如果開發文檔有遺漏，不完善，或內容陳舊，則管理者將失去跟蹤和控制項目的重要依據。

    4.2 任務之間聯系的憑證

    大多數軟件開發項目通常被劃分成若干個任務，并由不同的小組去完成。學科方面的專家建立項目，分析員闡述系統需求，設計員為程序員制定總體設計，程序員編制詳細的程序代碼，質量保證專家和審查員評價整個系統性能和功能的完整性，負責維護的程序員改進各種操作或增強某些功能。

    這些人員需要的互相聯系是通過文檔資料的復制、分發和引用而實現的，因而，任務之間的聯系是文檔的一個重要功能。大多數系統開發方法為任務的聯系規定了一些正式文檔。分析員向設計員提供正式需求規格說明，設計員向程序員提供正式設計規格說明，等等。

    4.3 質量保證

    那些負責軟件質量保證和評估系統性能的人員需要程序規格說明、測試和評估計劃、測試該系統用的各種質量標準以及關于期望系統完成什么功能和系統怎樣實現這些功能的清晰說明；必須制訂測試計劃和測試規程，并報告測試結果；他們還必須說明和評估完全、控制、計算、檢驗例行程序及其他控制技術。這些文檔的提供可滿足質量保證人員和審查人員上述工作的需要。

    4.4 培訓與參考

    軟件文檔的另一個功能是使系統管理員、操作員、用戶、管理者和其他有關人員了解系統如何工作，以及為了達到他們的各自的目的，如何使用系統。

    4.5 軟件維護支持

    維護人員需要軟件系統的詳細說明以幫助他們熟悉系統，找出并修正錯誤，改進系統以適應用戶需求的變化或適應系統環境的變化。

    4.6 歷史檔案

    軟件文檔可用作未來項目的一種資源。通常文檔記載系統的開發歷史，可使有關系統結構的基本思想為以后的項目利用。系統開發人員通過審閱以前的系統以查明什么部分已試驗過了，什么部分運行得很好，什么部分因某種原因難以運行而被排除。良好的系統文檔有助于把程序移植和轉移到各種新的系統環境中。

    5 管理者的作用

    管理者嚴格要求軟件開發人員和編制組完成文檔編制，并且在策略、標準、規程、資源分配和編制計劃方面給予支持。

    a) 管理者對文檔工作的責任。管理者要認識到正式或非正式文檔都是重要的，還要認識到文檔工作必須包括文檔計劃、編寫、修改、形成、分發和維護等各個方面。

    b) 管理者對文檔工作的支持。管理者應為編寫文檔的人員提供指導和實際鼓勵，并使各種資源有效地用于文檔開發。

    c) 管理者的主要職責：

    1 ） 建立編制、登記、出版系統文檔和軟件文檔的各種策略；

    2 ） 把文檔計劃作為整個開發工作的一個組成部分；

    3 ） 建立確定文檔質量、測試質量和評審質量的各種方法的規程；

    4 ） 為文檔的各個方面 確定和準備各種標準和指南；

    5 ） 積極支持文檔工作以形成在開發工作中自覺編制文檔的團隊風氣；

    6 ） 不斷檢查已建立起來的過程，以保證符合策略和各種規程并遵守有關標準和指南。

    通常，項目管理者在項目開發前應決定如下事項：

    要求哪些類型的文檔；

    提供多少種文檔；

    文檔包含的內容；

    達到何種級別的質量水平；

    何時產生何種文檔；

    如何保存、維護文檔以及如何進行通信。

    如果一個軟件合同是有效的，應要求文檔滿足所接受的標準，并規定所提供的文檔類型、每種文檔的質量水平以及評審和通過的規程。

    6 制訂文檔編制策略

    文檔策略是由上級（資深）管理者新任務并支持的，對下級開發單位或開發人員提供指導。策略規定主要的方向不是做什么或如何做的詳細說明。

    一般說來，文檔編制策略陳述要明確，并通告到每個人且理解它，進而使策略被他們貫徹實施。

    支持有效文檔策略的基本條件：

    a) 文檔需要覆蓋整個軟件生存期

    在項目早期幾個階段就要求有文檔，而且在貫穿軟件開發過程中必須是可用的和可維護的。在開發完成后，文檔應滿足軟件的使用、維護、增強、轉換或傳輸。

    b) 文檔應是可管理的

    指導和控制文檔的獲得維護，管理者和發行專家應準備文檔產品、進度、可靠性、資源，質量保證和評審規程的詳細計劃大綱。

    c) 文檔應適合于它的讀者

    讀者可能是管理者、分析員、無計算機經驗的專業人員、維護人員、文書人員等。根據任務的執行，他們要求不同的材料表示和不同的詳細程度。針對不同的讀者，發行專家應負責設計不同類型的文檔。

    d) 文檔效應應貫穿到軟件的整個開發過程中

    在軟件開發的整個過程中，應充分體現文檔的作用和限制，即文檔應指導全部開發過程。

    e) 文檔標準應被標識和使用

    應盡可能地采納現行的標準，若沒有合適的現行標準，必要時應研制適用的標準或指南。

    f) 應規定支持工具

    工具有助于開發和維護軟件產品，包括文檔。因此盡可能地使用工具是經濟的、可行的。

    附錄 A 中的檢查表為制定策略條款或評估現有策略條款的有效性和完整性提供幫助。

    7 制訂文檔編制標準和指南

    在一個機構內部，應采用一些標準和指南：

    ——軟件生存期模型；

    ——文檔類型和相互關系；

    ——文檔質量。

    這些標準和指南決定如何實現文檔任務，將提供一些準則以評價機構內所產生的軟件文檔的完整性、可用性和適合性。

    盡可能地采用現行的國家和國際標準，若現行的標準不適用，機構應制訂自己的標準。

    7.1 選擇軟件生存期模型

    現有的一些軟件生存期模型，對于不同的階段有不同的詞匯，從軟件文檔的觀點來看，采用哪種模型都無關緊要，只要階段和相應的文檔是清晰定義的、已計劃的，并且對于任何具體軟件項目是能遵循的。因此，管理者應選擇一個軟件生存期模型并保證該模型在他們機構內是適用的。

    管理者將會發現所進行的階段和相應任務的定義有助于監控軟件項目的進展。相應于特定階段生成的文檔可用作該階段的評審、通過和完成的檢驗點，而這種檢驗應在下一階段開始前進行。

    7.2 規定文檔類型和內容

    下面給出軟件文檔主要類型的大綱，這個大綱不是詳盡的或最后的，但適合作為主要類型軟件文檔的檢驗表。而管理者應規定何時定義他們的標準文檔類型。

    軟件文檔歸入如下三種類別：

    a) 開發文檔——描述開發過程本身；

    b) 產品文檔——描述開發過程的產物；

    c) 管理文檔——記錄項目管理的信息。

    7.2.1 開發文檔

    開發文檔是描述軟件開發過程，包括軟件需求、軟件設計、軟件測試、保證軟件質量的一類文檔，開發文檔也包括軟件的詳細技術描述（程序邏輯、程序間相互關系、數據格式和存儲等）。

    開發文檔起到如下五種作用：

    a) 它們是軟件開發過程中包含的所有階段之間的通信工具，它們記錄生成軟件需求、設計、編碼和測試的詳細規定和說明；

    b) 它們描述開發小組的職責。通過規定軟件、主題事項、文檔編制、質量保證人員以及包含在開發過程中任何其他事項的角色來定義做直截了當、如何做和何時做；

    c) 它們用作檢驗點而允許管理者評定開發進度。如果開發文檔丟失、不完整或過時，管理者將失去跟蹤和控制軟件項目的一個重要工具；

    d) 它們形成了維護人員所要求的基本的軟件支持文檔。而這些支持文檔可作為產品文檔的一部分；

    e) 它們記錄軟件開發的歷史。

    基本的開發文檔是：

    ——可行性研究和項目任務書；

    ——需求規格說明；

    ——功能規格說明；

    ——設計規格說明，包括程序和數據規格說明；

    ——開發計劃；

    ——軟件集成和測試計劃；

    ——質量保證計劃、標準、進度；

    安全和測試信息。

    7.2.2 產品文檔

    產品文檔規定關于軟件產品的使用、維護、增強、轉換和傳輸的信息。

    產品的文檔起到如下三種作用：

    a) 為使用和運行軟件產品的任何人規定培訓和參考信息；

    b) 使得那些未參加開發本軟件的程序員維護它；

    c) 促進軟件產品的市場流通或提高可接受性。

    產品文檔用于下列類型的讀者：

    ——用戶 ——他們利用軟件輸入數據、檢索信息和解決問題；

    ——運行者 ——他們在計算機系統上運行軟件；

    ——維護人員 ——他們維護、增強或變更軟件。

    產品文檔包括如下內容：

    ——用于管理者的指南和資料，他們監督軟件的使用；

    ——宣傳資料 通告軟件產品的可用性并詳細說明它的功能、運行環境等；

    ——一般信息 對任何有興趣的人描述軟件產品。

    基本的產品文檔包括：

    ——培訓手冊；

    ——參考手冊和用戶指南；

    ——軟件支持手冊；

    ——產品手冊和信息廣告。

    7.2.3 管理文檔

    這種文檔建立在項目管理信息的基礎上，諸如：

    ——開發過程的每個階段的進度和進度變更的記錄；

    ——軟件變更情況的記錄；

    ——相對于開發的判定記錄；

    ——職責定義。

    這種文檔從管理的角度規定涉及軟件生存的信息。

    相關文檔的詳細規定和編寫格式見 GB 8567 。

    7.3 確定文檔的質量等級

    僅僅依據規章、傳統的做法或合同的要求去制作文檔是不夠的。管理者還必須確定文檔的質量要求以及如何達到和保證質量要求。

    質量要求的確定取決于可得到的資源、項目的大小和風險，可以對該產品的每個文檔的格式及詳細程度作出明確的規定。

    每個文檔的質量必須在文檔計劃期間就有明確的規定。文檔的質量可以按文檔的形式和列出的要墳劃分為四級。

    最低限度文檔（ 1 級文檔） 1 級文檔適合開發工作量低于一個人月的開發者自用程序。該文檔應包含程序清單、開發記錄、測試數據和程序簡介。

    內部文檔（ 2 級文檔） 2 級文檔可用于在精心研究后被認為似乎沒有與其他用戶共享資源的專用程序。除 1 級文檔提供的信息外， 2 級文檔還包括程序清單內足夠的注釋以幫助用戶安裝和使用程序。

    工作文檔（ 3 級文檔） 3 級文檔適合于由同一單位內若干人聯合開發的程序，或可被其他單位使用的程序。

    正式文檔（ 4 級文檔） 4 級文檔適合那些要正式發行供普遍使用的軟件產品。關鍵性程序或具有重復管理應用性質（如工資計算）的程序需要 4 級文檔。 4 級文檔遵守 GB 8567 的有關規定。

    質量方面需要考慮的問題即要包含文檔的結構，也要包含文檔的內容。文檔內容可以根據正確性、完整性和明確性來判斷。而文檔結構由各個組成部分的順序和總體安排的簡單性來測定。要達到這四個質量等級，需要的投入和資源逐級增加，質量保證機構必須處于適當的行政地位以保證達到期望的質量等級。

    8 文檔編制計劃

    文檔計劃可以是整個項目計劃的一部分或是一個獨立的文檔。應該編寫文檔計劃并把它分發給全體開發組成員，作為文檔重要性的具體依據和管理部門文檔工作責任的備忘錄。

    對于小的、非正式的項目，文檔計劃可能只有一頁紙；對于較大的項目，文檔計劃可能是一個綜合性的正式文檔，這樣的文檔計劃應遵循各項嚴格的標準及正規的評審和批準過程。

    編制計劃的工作應及早開始，對計劃的評審應貫穿項目的全過程。如同任何別的計劃一樣，文檔計劃指出未來的各項活動，當需要修改時必須加以修改。導致對計劃作適當修改的常規評審應作為該項目工作的一部分，所有與該計劃有關的人員都應得到文檔計劃。

    文檔計劃一般包括以下幾方面內容：

    a) 列出應編制文檔的目錄；

    b) 提示編制文檔應參考的標準；

    c) 指定文檔管理員；

    d) 提供編制文檔所需要的條件，落實文檔編寫人員、所需經費以及編制工具等；

    e) 明確保證文檔質量的方法，為了確保文檔內容的正確性、合理性，應采取一定的措施，如評審、鑒定等等；

    f) 繪制進度表，以圖表形式列出在軟件生存期各階段應產生的文檔、編制人員、編制日期、完成日期、評審日期等。

    附錄 B 中的檢查表為制定一個文檔計劃或評估現有文檔計劃的完整性提供幫助。

    此外，文檔計劃規定每個文檔要達到的質量等級，以及為了達到期望的結果必須考慮哪些外部因素。

    文檔計劃還確定該計劃和文檔的分發，并且明確敘述與文檔工作的所有人員的職責。

文章來源于領測軟件測試網 http://www.kjueaiud.com/

TAG: 管理 軟件文檔