軟件文檔(document)也稱文件，通常指的是一些記錄的數據 和數據媒體，它具有固定不變的形式，可被人和計算機閱讀。它和 計算機程序共同構成了能完成特定功能的計算機軟件(有人把源 程序也當作文檔的一部分)。我們知道，硬件產品和產品資料在整 個生產過程中都是有形可見的，軟件生產則有很大不同，文檔本 身就是軟件產品。沒有文檔的軟件，不成其為軟件，更談不到軟件 產品。軟件文檔的編制(documentation)在軟件開發工作中占有突 出的地位和相當的工作量。高效率、高質量地開發、分發、管理和維 護文檔對于轉讓、變更、修正、擴充和使用文檔，對于充分發揮軟 件產品的效益有著重要意義。
然而，在實際工作中，文檔在編制和使用中存在著許多問 題，有待于解決。軟件開發人員中較普遍地存在著對編制文檔不感 興趣的現象。從用戶方面看，他們又常常抱怨：文檔售價太高、文 檔不夠完整、文檔編寫得不好、文檔已經陳舊或是文檔太多，難于 使用等等。究竟應該怎樣要求它，文檔應該寫哪些，說明什么問 題，起什么作用?這里將給出簡要的介紹。
圖9.2 文檔橋梁作用
文檔在軟件開發人員、軟件管理人員、維護人員、用戶以及計 算機之間的多種橋梁作用可從圖9．2中看出。軟件開發人員在各 個階段中以文檔作為前階段工作成果的體現和后階段工作的依 據，這個作用是顯而易見的。軟件開發過程中軟件開發人員需制定 一些工作計劃或工作報告，這些計劃和報告都要提供給管理人員， 并得到必要的支持。管理人員則可通過這些文檔了解軟件開發項 目安排、進度、資源使用和成果等。軟件開發人員需為用戶了解軟 件的使用、操作和維護提供詳細的資料，我們稱此為用戶文檔。以 上三種文檔構成了軟件文檔的主要部分。我們把這三種文檔所包 括的內容列在圖6中。其中列舉了十三個文檔，這里對它們作 一些簡要說明：
可行性研究報告：說明該軟件開發項目的實現在技術上、經 濟上和社會因素上的可行性，評述為了合理地達到開發目標可供 選擇的各種可能實施的方案，說明并論證所選定實施方案的理 由。
項目開發計劃：為軟件項目實施方案制定出具體計劃，應 該包括各部分工作的負責人員、開發的進度、開發經費的預算、所 需的硬件及軟件資源等。項目開發計劃應提供給管理部門，并作 為開發階段評審的參考。
軟件需求說明書：也稱軟件規格說明書，其中對所開發軟 件的功能、性能、用戶界面及運行環境等作出詳細的說明。它是用 戶與開發人員雙方對軟件需求取得共同理解基礎上達成的協議， 也是實施開發工作的基礎。
數據要求說明書：該說明書應給出數據邏輯描述和數據采 集的各項要求，為生成和維護 系統數據文卷作好準備。
概要設計說明書：該說 明書是概要設計階段的工作 成果，它應說明功能分配、模 塊劃分、程序的總體結構、輸 入輸出以及接口設計、運行設 計、數據結構設計和出錯處理 設計等，為詳細設計奠定基 礎。
詳細設計說明書：著重 描述每一模塊是怎樣實現的， 包括實現算法、邏輯流程等。
用戶手冊：本手冊詳細 描述軟件的功能、性能和用戶 界面，使用戶了解如何使用該軟件。
| 文檔 |
 |
用戶文檔 |
 |
用戶手冊 |
| 操作手冊 |
| 維護修改建議 |
| 軟件需求（規格）說明書 |
| 開發文檔 |
 |
軟件需求（規格）說明書 |
| 數據要求說明書 |
| 概要設計說明書 |
| 詳細設計說明書 |
| 可行性研究報告 |
| 項目開發計劃 |
| 管理文檔 |
 |
項目開發計劃 |
| 測試計劃 |
| 測試報告 |
| 開發進度月報 |
| 開發總結報告 |
圖9.3 三種文檔
操作手冊：本手冊為操作人員提供該軟件各種運行情況的 有關知識，特別是操作方法的具體細節。
測試計劃：為做好組裝測試和確認測試，需為如何組織測試 制定實施計劃。計劃應包括測試的內容、進度、條件、人員、測試用 例的選取原則、測試結果允許的偏差范圍等。
測試分析報告：測試工作完成以后，應提交測試計劃執行 情況的說明。對測試結果加以分析，并提出測試的結論意見。
開發進度月報：該月報系軟件人員按月向管理部門提交的 項目進展情況報告。報告應包括進度計劃與實際執行情況的比較、 階段成果、遇到的問題和解決的辦法以及下個月的打算等。
項目開發總結報告：軟件項目開發完成以后，應與項目實 施計劃對照，總結實際執行的情況，如進度、成果、資源利用、成本 和投入的人力。此外還需對開發工作作出評價，總結出經驗和教 訓。
維護修改建議，軟件產品投入運行以后，發現了需對其進 行修正、更改等問題，應將存在的問題、修改的考慮以及修改的影 響估計作詳細的描述，寫成維護修改建議，提交審批。 以上這些文檔是在軟件生存期中，隨著各階段工作的開展適 時編制。其中有的僅反映一個階段的工作，有的則需跨越多個階 段。表5給出了各個文檔應在軟件生存期中哪個階段編寫。這 些文檔最終要向軟件管理部門，或是向用戶回答以下的問題：
表9.2 軟件生存期各階段編制的文檔
|
階段
文檔 |
可行性藥酒與計劃 |
需求分析 |
設計 |
代碼編寫 |
測試 |
運行與維護 |
| 可行性研究報告 |
|
|
|
|
|
|
| 項目開發計劃 |
|
|
|
|
|
|
| 軟件需求說明 |
|
|
|
|
|
|
| 數據要求說明 |
|
|
|
|
|
|
| 概要設計說明 |
|
|
|
|
|
|
| 星系設計說明 |
|
|
|
|
|
|
| 測試計劃 |
|
|
|
|
|
|
| 用戶手冊 |
|
|
|
|
|
|
| 操作手冊 |
|
|
|
|
|
|
| 測試分析報告 |
|
|
|
|
|
|
| 開發進度月報 |
|
|
|
|
|
|
| 項目開發總結 |
|
|
|
|
|
|
| 維護修改建議 |
|
|
|
|
|
|
哪些需求要被滿足，即回答“做什么?”
所開發的軟件在什么環境中實現以及所需信息從哪里來， 即回答“從何處?”
某些開發工作的時間如何安排，即回答“何時干?”
某些開發(或維護)工作打算由“誰來干?”
某些需求是怎么實現的?
為什么要進行那些軟件開發或維護修改工作?
上述十三個文檔都在一定程度上回答了這六個方面的問題。這可從表中看到。
表9.3 文檔所回答的問題
|
所提問題
文檔 |
什么 |
何處 |
何時 |
誰 |
如何 |
為何 |
|
可行性研究報告 |
√ |
|
|
|
|
√ |
|
項目開發計劃 |
√ |
|
√ |
√ |
|
|
|
軟件需求說明 |
√ |
√ |
|
|
|
|
|
數據要求說明 |
√ |
√ |
|
|
|
|
|
概要設計說明 |
|
|
|
|
√ |
|
|
詳細設計說明 |
|
|
|
|
√ |
|
|
測試計劃 |
|
|
√ |
√ |
√ |
|
|
用戶手冊 |
|
|
|
|
√ |
|
|
操作手冊 |
|
|
|
|
√ |
|
|
測試分析報告 |
√ |
|
|
|
|
|
|
開發進度月報 |
√ |
|
√ |
|
|
|
|
項目開發總結 |
√ |
|
|
|
|
|
|
維護修改建議 |
√ |
|
|
√ |
|
√ |
至此，我們對文檔的作用有了進一步的理解。每一個文檔的任 務也是明確的，任何一個文檔都此是多余的。