軟件文檔
軟件文檔 文檔的作用和分類 軟件文檔(document)也稱文件，通常指的是一些記錄的數(shù)據(jù) 和數(shù)據(jù)媒體，它具有固定不變的形式，可被人和計算機閱讀。它和 計算機程序共同構(gòu)成了能完成特定功能的計算機軟件(有人把源 程序也當作文檔的一部分)。我們知道，硬件產(chǎn)品和產(chǎn)品資料在整 個生產(chǎn)過程中都是有形可見的，軟件生產(chǎn)則有很大不同，文檔本 身就是軟件產(chǎn)品。沒有文檔的軟件，不成其為軟件，更談不到軟件 產(chǎn)品。軟件文檔的編制(documentation)在軟件開發(fā)工作中占有突 出的地位和相當?shù)墓ぷ髁?。高效率、高質(zhì)量地開發(fā)、分發(fā)、管理和維 護文檔對于轉(zhuǎn)讓、變更、修正、擴充和使用文檔，對于充分發(fā)揮軟 件產(chǎn)品的效益有著重要意義。 然而，在實際工作中，文檔在編制和使用中存在著許多問 題，有待于解決。軟件開發(fā)人員中較普遍地存在著對編制文檔不感 興趣的現(xiàn)象。從用戶方面看，他們又常常抱怨：文檔售價太高、文 檔不夠完整、文檔編寫得不好、文檔已經(jīng)陳舊或是文檔太多，難于 使用等等。究竟應(yīng)該怎樣要求它，文檔應(yīng)該寫哪些，說明什么問 題，起什么作用?這里將給出簡要的介紹。 圖 文檔橋梁作用 文檔在軟件開發(fā)人員、軟件管理人員、維護人員、用戶以及計 算機之間的多種橋梁作用可從圖9．2中看出。軟件開發(fā)人員在各 個階段中以文檔作為前階段工作成果的體現(xiàn)和后階段工作的依 據(jù)，這個作用是顯而易見的。軟件開發(fā)過程中軟件開發(fā)人員需制定 一些工作計劃或工作報告，這些計劃和報告都要提供給管理人員， 并得到必要的支持。管理人員則可通過這些文檔了解軟件開發(fā)項 目安排、進度、資源使用和成果等。軟件開發(fā)人員需為用戶了解軟 件的使用、操作和維護提供詳細的資料，我們稱此為用戶文檔。以 上三種文檔構(gòu)成了軟件文檔的主要部分。我們把這三種文檔所包 括的內(nèi)容列在圖6中。其中列舉了十三個文檔，這里對它們作 一些簡要說明： o 可行性研究報告：說明該軟件開發(fā)項目的實現(xiàn)在技術(shù)上、經(jīng) 濟上和社會因素上的可行性，評述為了合理地達到開發(fā)目標可供 選擇的各種可能實施的方案，說明并論證所選定實施方案的理 由。 o 項目開發(fā)計劃：為軟件項目實施方案制定出具體計劃，應(yīng) 該包括各部分工作的負責(zé)人員、開發(fā)的進度、開發(fā)經(jīng)費的預(yù)算、所 需的硬件及軟件資源等。項目開發(fā)計劃應(yīng)提供給管理部門，并作 為開發(fā)階段評審的參考。 o 軟件需求說明書：也稱軟件規(guī)格說明書，其中對所開發(fā)軟 件的功能、性能、用戶界面及運行環(huán)境等作出詳細的說明。它是用 戶與開發(fā)人員雙方對軟件需求取得共同理解基礎(chǔ)上達成的協(xié)議， 也是實施開發(fā)工作的基礎(chǔ)。 o 數(shù)據(jù)要求說明書：該說明書應(yīng)給出數(shù)據(jù)邏輯描述和數(shù)據(jù)采 集的各項要求，為生成和維護 系統(tǒng)數(shù)據(jù)文卷作好準備。 o 概要設(shè)計說明書：該說 明書是概要設(shè)計階段的工作 成果，它應(yīng)說明功能分配、模 塊劃分、程序的總體結(jié)構(gòu)、輸 入輸出以及接口設(shè)計、運行設(shè) 計、數(shù)據(jù)結(jié)構(gòu)設(shè)計和出錯處理 設(shè)計等，為詳細設(shè)計奠定基 礎(chǔ)。 o 詳細設(shè)計說明書：著重 描述每一模塊是怎樣實現(xiàn)的， 包括實現(xiàn)算法、邏輯流程等。 o用戶手冊：本手冊詳細 描述軟件的功能、性能和用戶 界面，使用戶了解如何使用該軟件。 文檔 用戶文檔 用戶手冊 操作手冊 維護修改建議 軟件需求（規(guī)格）說明書 開發(fā)文檔 軟件需求（規(guī)格）說明書 數(shù)據(jù)要求說明書 概要設(shè)計說明書 詳細設(shè)計說明書 可行性研究報告 項目開發(fā)計劃 管理文檔 項目開發(fā)計劃 測試計劃 測試報告 開發(fā)進度月報 開發(fā)總結(jié)報告 o 圖 三種文檔 o 操作手冊：本手冊為操作人員提供該軟件各種運行情況的 有關(guān)知識，特別是操作方法的具體細節(jié)。 o 測試計劃：為做好組裝測試和確認測試，需為如何組織測試 制定實施計劃。計劃應(yīng)包括測試的內(nèi)容、進度、條件、人員、測試用 例的選取原則、測試結(jié)果允許的偏差范圍等。 o 測試分析報告：測試工作完成以后，應(yīng)提交測試計劃執(zhí)行 情況的說明。對測試結(jié)果加以分析，并提出測試的結(jié)論意見。 o 開發(fā)進度月報：該月報系軟件人員按月向管理部門提交的 項目進展情況報告。報告應(yīng)包括進度計劃與實際執(zhí)行情況的比較、 階段成果、遇到的問題和解決的辦法以及下個月的打算等。 o 項目開發(fā)總結(jié)報告：軟件項目開發(fā)完成以后，應(yīng)與項目實 施計劃對照，總結(jié)實際執(zhí)行的情況，如進度、成果、資源利用、成本 和投入的人力。此外還需對開發(fā)工作作出評價，總結(jié)出經(jīng)驗和教 訓(xùn)。 o 維護修改建議，軟件產(chǎn)品投入運行以后，發(fā)現(xiàn)了需對其進 行修正、更改等問題，應(yīng)將存在的問題、修改的考慮以及修改的影 響估計作詳細的描述，寫成維護修改建議，提交審批。 以上這些文檔是在軟件生存期中，隨著各階段工作的開展適 時編制。其中有的僅反映一個階段的工作，有的則需跨越多個階 段。表5給出了各個文檔應(yīng)在軟件生存期中哪個階段編寫。這 些文檔最終要向軟件管理部門，或是向用戶回答以下的問題： 表9.2 軟件生存期各階段編制的文檔 階段 文檔 可行性藥酒與計劃 需求分析 設(shè)計 代碼編寫 測試 運行與維護 可行性研究報告 項目開發(fā)計劃 軟件需求說明 數(shù)據(jù)要求說明 概要設(shè)計說明 星系設(shè)計說明 測試計劃 用戶手冊 操作手冊 測試分析報告 開發(fā)進度月報 項目開發(fā)總結(jié) 維護修改建議 o o 哪些需求要被滿足，即回答“做什么?” o 所開發(fā)的軟件在什么環(huán)境中實現(xiàn)以及所需信息從哪里來， 即回答“從何處?” o 某些開發(fā)工作的時間如何安排，即回答“何時干?” o 某些開發(fā)(或維護)工作打算由“誰來干?” o 某些需求是怎么實現(xiàn)的? o 為什么要進行那些軟件開發(fā)或維護修改工作? 上述十三個文檔都在一定程度上回答了這六個方面的問題。這可從表中看到。 表 文檔所回答的問題 所提問題 文檔 什么 何處 何時 誰 如何 為何 可行性研究報告 √ √ 項目開發(fā)計劃 √ √ √ 軟件需求說明 √ √ 數(shù)據(jù)要求說明 √ √ 概要設(shè)計說明 √ 詳細設(shè)計說明 √ 測試計劃 √ √ √ 用戶手冊 √ 操作手冊 √ 測試分析報告 √ 開發(fā)進度月報 √ √ 項目開發(fā)總結(jié) √ 維護修改建議 √ √ √ 至此，我們對文檔的作用有了進一步的理解。每一個文檔的任 務(wù)也是明確的，任何一個文檔都此是多余的。 文檔的管理和維護 在整個軟件生存期中，各種文檔作為半成品或是最終成品， 會不斷地生成、修改或補充。為了最終得到高質(zhì)量的產(chǎn)品，達到上 節(jié)提出的質(zhì)量要求，必須加強對文檔的管理。以下幾個方面是應(yīng)注意做到的： ①軟件開發(fā)小組應(yīng)設(shè)一位文檔保管人員，負責(zé)集中保管本 項目已有文檔的兩套主文本。兩套文本內(nèi)容完全一致。其中的一套可按一定手續(xù)，辦理 借閱。 ②軟件開發(fā)小組的成員可根據(jù)工作需要在自己手中保存一些個人文檔。這些一般都應(yīng)是主 文本的復(fù)制件，并注意和主文本保持一致，在作必要的修改時，也應(yīng)先修改主文本。 ③開發(fā)人員個人只保存著主文本中與他工作相關(guān)的部分文檔。 ④在新文檔取代了舊文檔時，管理人員應(yīng)及時注銷舊文檔。 在文檔內(nèi)容有更動時，管理人員應(yīng)隨時修訂主文本，使其及時反映更新了的內(nèi)容。 ⑤項目開發(fā)結(jié)束時，文檔管理人員應(yīng)收回開發(fā)人員的個人文檔。發(fā)現(xiàn)個人文檔與主文本有 差別時，應(yīng)立即著手解決。這常常是未及時修訂主文本造成的。 ⑥在軟件開發(fā)過程中，可能發(fā)現(xiàn)需要修改已完成的文檔，特別是規(guī)模較大的項目，主文本 的修改必須特別謹慎。修改以前要充分估計修改可能帶來的影響，并且要按照：提議、 評議、審核、批準和實施等步驟加以嚴格的控制。 文檔編制的質(zhì)量要求 為了使軟件文檔能起到前節(jié)所提到的多種橋梁作用，使它有 助于程序員編制程序，有助于管理人員監(jiān)督和管理軟件開發(fā)，有助 于用戶了解軟件的工作和應(yīng)做的操作，有助于維護人員進行有效 的修改和擴充，文檔的編制必須保證一定的質(zhì)量。質(zhì)量差的軟件文 檔不僅使讀者難于理解，給使用者造成許多不便，而且會削弱對 軟件的管理(管理人員難以確認和評價開發(fā)工作的進展)，增高軟 件的成本(一些工作可能被迫返工)，甚至造成更加有害的后果(如誤操作等)。 造成軟件文檔質(zhì)量不高的原因可能是： o缺乏實踐經(jīng)驗，缺乏評價文檔質(zhì)量的標準。 o不重視文檔編寫工作或是對文檔編寫工作的安排不恰當。 最常見到的情況是，軟件開發(fā)過程中不能按表5給出的進度， 分階段及o時完成文檔的編制工作，而是在開發(fā)工作接近完成時集 中人力和時間專門編寫文檔。另一方面，和程序工作相比，許多 人對編制文檔不感興趣。于是在程序工作完成以后，不得不應(yīng)付 一下，把要求提供的文檔趕寫出來。這樣的做法不可能得到高質(zhì) 量的文檔。實際上，要得到真正高質(zhì)量的文檔并不容易，除去應(yīng)在 認識上對文檔工作給予足夠的重視外，常常需要經(jīng)過編寫初稿， 聽取意見進行修改，甚至要經(jīng)過重新改寫的過程。 高質(zhì)量的文檔應(yīng)當體現(xiàn)在以下一些方面： ①針對性；文檔編制以前應(yīng)分清讀者對象，按不同的類型、不 同層次的讀者，決定怎樣適應(yīng)他們的需要。例如，管理文檔主要是 面向管理人員的，用戶文檔主要是面向用戶的，這兩類文檔不應(yīng) 像開發(fā)文檔(面向軟件開發(fā)人員)那樣過多地使用軟件的專業(yè)術(shù)語。 ②精確性：文檔的行文應(yīng)當十分確切，不能出現(xiàn)多義性的描 述。同一課題若干文檔內(nèi)容應(yīng)該協(xié)調(diào)一致，應(yīng)是沒矛盾的。 ⑧清晰性：文檔編寫應(yīng)力求簡明，如有可能，配以適當?shù)膱D 表，以增強其清晰性。 ④完整性：任何一個文檔都應(yīng)當是完整的、獨立的，它應(yīng)自成 體系。例如，前言部分應(yīng)作一般性介紹，正文給出中心內(nèi)容，必要 時還有附錄，列出參考資料等。同一課題的幾個文檔之間可能有些 部分相同，這些重復(fù)是必要的。例如，同一項目的用戶手冊和操作 手冊中關(guān)于本項目功能、性能、實現(xiàn)環(huán)境等方面的描述是沒有差別 的。特別要避免在文檔中出現(xiàn)轉(zhuǎn)引其它文檔內(nèi)容的情況。比如，一 些段落并未具體描述，而用“見××文檔××節(jié)”的方式，這將給 讀者帶來許多不便。 ⑤靈活性：各個不同的軟件項目，其規(guī)模和復(fù)雜程度有著許 多實際差別，不能一律看待。圖6所列文檔是針對中等規(guī)模 的軟件而言的。對于較小的或比較簡單的項目，可做適當調(diào)整或合 并。比如，可將用戶手冊和操作手冊合并成用戶操作手冊；軟件需 求說明書可包括對數(shù)據(jù)的要求，從而去掉數(shù)據(jù)要求說明書；概要設(shè) 計說明書與詳細設(shè)計說明書合并成軟件設(shè)計說明書等。 ⑥可追溯性；由于各開發(fā)階段編制的文檔與各階段完成的工 作有著緊密的關(guān)系，前后兩個階段生成的文檔，隨著開發(fā)工作的逐 步擴展，具有一定的繼承關(guān)系。在一個項目各開發(fā)階段之間提供的 文檔必定存在著可追溯的關(guān)系。例如，某一項軟件需求，必定在設(shè) 計說明書，測試計劃以至用戶手冊中有所體現(xiàn)。必要時應(yīng)能做到 跟蹤追查。 程序文檔合一與動態(tài)文檔 很多企業(yè)已經(jīng)建立了許多龐大的計算機管理系統(tǒng)，而且將不斷地推出新的系統(tǒng)。滿足經(jīng) 營的需求須不斷維護、改造計算機系統(tǒng)，但同時又要不影響現(xiàn)行生產(chǎn)，所以必須建立一 整套機制來評價、控制和完成對系統(tǒng)的維護。在軟件維護過程中，提出程序與文檔合一 的概念在軟件開發(fā)的同時建立動態(tài)文檔。 程序與文檔合一概念的提出 一、目前軟件的狀況 　　程序與文檔的形式分離，不僅是用各自獨立的形式存放，而且使用不同的工具在不 同的時間里書寫和檢索。維護程序時不能方便地得到文檔的幫助，不能同步修改文檔。 　　程序與文檔的內(nèi)容分離，由于程序與文檔采用不同的描述，既有計算機語言也有自 然語言。維護過程中不能及時、一致地更新文檔或程序，使文檔不能準確地描述程序而 幾乎成為廢紙甚至帶來負面價值。 　　軟件開發(fā)與維護的分離，絕大多數(shù)軟件在設(shè)計、開發(fā)時不太考慮以后可能的修改， 加大了軟件維護的難度，而且使維護容易引入新的錯誤。 　　這些分離也表現(xiàn)在設(shè)計、開發(fā)的不同階段的文檔之間的不相容性，例如：需求分析 說明書是紙上的東西，在概要設(shè)計階段不能很好地繼承、利用需求分析說明書，設(shè)計、 編制概要設(shè)計時必須從零開始，需要重新分析、理解需求分析，這種思維上的脫節(jié)，不 僅延緩開發(fā)進度、加重設(shè)計人員的負擔，而且由于理解上的不同導(dǎo)致不同階段描述的對 象有許多不相容情況。這些分離使得文檔在系統(tǒng)的設(shè)計、開發(fā)、維護中的作用下降，這 也是很多軟件人員不愿意編寫文檔的主要原因。 二、程序與文檔合一的概念提出 　　怎樣才是好的文檔系統(tǒng)呢？應(yīng)當具備以下屬性： 　　1. 能夠準確地描述軟件、...
軟件文檔