文檔編製

如果不重視文檔編寫工作，或是對文檔編寫工作的安排不當，就不可能得到高質量的文檔。質量差的文檔不僅使讀者難於理解，給使用者造成許多不便，而且會削弱對軟體的管理(難以確認和評價開發工作的進展情況)，提高軟體成本(一些工作可能被迫返工)，甚至造成更加有害的後果(如誤操作等)。

文檔編製以前應分清讀者對象。按不同的類型、不同層次的讀者，決定怎樣適應他們的需要。例如，管理文檔主要是面向管理人員的，用戶文檔主要是面向用戶的，這兩類文檔不應像開發文檔(面向開發人員)那樣過多使用軟體的專用術語。

文檔的行文應當十分確切，不能出現多義性的描述。同一課題幾個文檔的內容應當是協調一致，沒有矛盾的。

文檔編寫應力求簡明，如有可能，配以適當的圖表，以增強其清晰性。

任何一個文檔都應當是完整的、獨立的，它應自成體系。例如，前言部分應做一般性介紹，正文給出中心內容，必要時還有附錄，列出參考資料等。

同一課題的幾個文檔之間可能有些部分內容相同，這種重複是必要的。不要在文檔中出現轉引其他文檔內容的情況。例如，一些段落沒有具體描述，而用“見××文檔x×節，，的方式，這將給讀者帶來許多的不便。

各個不同軟體項目，其規模和複雜程度有著許多實際差別，能一律看待。

應根據具體的軟體開發項目，決定編製的文檔種類。軟體開發的管理部門應該根據本單位承擔的應用軟體的專業領域和本單位的管理能力，制定一個對文檔編製要求的實施規定。主要是：在不同條件下，應該形成哪些文檔？這些文檔的詳細程度？該開發單位每一個項目負責人都應當認真執行這個實施規定。對於一個具體的應用軟體項目，項目負責人應根據上述實施規定，確定一個文檔編製計劃。其中包括：應該編製哪幾種文檔，詳細程度如何。各個文檔的編製負責人和進度要求。審查、批准的負責人和時間進度安排。在開發時期內文檔的維護、修改和管理的負責人，以及批准手續。有關的開發人員必須嚴格執行這個文檔編製計劃。

當所開發的軟體系統非常大時，一種文檔可以分成幾卷編寫。例如，項目開發計劃可分寫為：質量保證計劃、配置管理計劃、用戶培訓計劃、安裝實施計劃等。系統設計說明書可分寫為：系統設計說明書、子系統設計說明書。程序設計說明書可分寫為：程序設計說明書、介面設計說明書、版本說明。操作手冊可分為：操作手冊、安裝實施過程。測試計劃可分寫為：測試計劃、測試設計說明、測試規程。報告可分寫為：綜合測試報告、驗收測試報告。項目開發總結報告也可分寫成：項目開發總結報告、資源環境統計。

1.應根據任務的規模、複雜性、項目負責人對該軟體的開發過程及運行環境所需詳細程度的判斷，確定文檔的詳細程度。

2.對國標GB8567—88《計算機軟體產品開發文件編製指南》所建議的所有條款都可以擴展，進一步細分，以適應需要；反之，如果條款中有些細節並非必需，也可以根據實際情況壓縮合併。

3.程序的設計表現形式，可以使用程序流程圖、判定表、程序描述語言(PDI，)、或問題分析圖(PAD)等。

4.對於文檔的表現形式，沒有規定或限制。可以使用自然語言、也可以使用形式化的語言。

5.當國標《計算機軟體產品開發文件編製指南》中所規定的文檔種類不能滿足某些應用部門的特殊需要時，可以建立一些特殊的文檔種類要求。這些要求可以包含在本單位的文檔編製實施規定中。

《軟體產品開發文件編製指南》中給出了一個例子，利用求和法綜合衡量12種考慮因素，來確定應編製文檔的種類。使用這個方法的具體過程如下：

a.針對錶所列的12種衡量因素，考察所開發的軟體。對每一種因素給出一個分值，其範圍從1到5。

b.把衡量所得的各個因素的值相加，得總和之值。

c.根據總和之值，對錶表進行查找，確定應編製的文檔的種類。

其中，數據要求說明書欄用**表示應當根據所開發軟體的實際需要來確定是否需要編製這個文檔。測試分析報告欄用*表示這個文檔應該編寫，但不必很正規。

(6)可追溯性：

由於各開發階段編製的文檔與各個階段完成的工作有密切的關係，前後兩個階段生成的文檔，隨著開發工作的逐步延伸，具有一定的繼承關係，在一個項目各開發階段之間提供的文檔必定存在著可追溯的關係。例如，某一項軟體需求，必定在設計說明書、測試計劃、甚至用戶手冊中有所體現。必要時應能做到跟蹤追查。