软件文档编写指南

1、軟體文檔編寫指南封面格式：文檔編號版本號文檔名稱：專案名稱：專案負責人：編寫年月日校對年月日審核年月日批准年月日開發單位系統規約說明書(System Specification )一引言A. 文檔的範圍和目的B. 概述1. 目標2. 約束二. 功能和數據描述A. 系統結構1 .結構關係圖2.結構關係圖描述三. 子系統描述A. 子系統N的結構圖規約說明B. 結構字典C. 結構連接圖和說明四. 系統建模和模擬結構A.用於模擬的系統模型B. 模擬結果C. 特殊性能 五軟體專案問題A. 軟體專案可行性研究報告B. 軟體專案計畫 六附錄軟體專案可行性研究報告Report for FeasibilityS

2、tudy )一引言1編寫目的（闡明編寫可行性研究報告的目的，指出讀者對象）2專案背景（應包括： （1）所建議開發的軟體名稱； （ 2）專案的任務提出者、開發者、 用戶及實現單位； （ 3）專案與其他軟體或其他系統的關係。 ）3定義（列出文檔中用到的專門術語的定義和縮略詞的原文。）4參考資料（列出有關資料的作者、標題、編號、發表日期、出版單位或資料來源。）二可行性研究的前提1 要求（列出並說明建議開發軟體的基本要求，如（1）功能；（ 2）性能；（3）輸出；（ 4）輸入；（5）基本的數據流程和處理流程； （ 6）安全與保密要求； （7）與軟體相關的其 他系統；（ 8）完成期限。 ）2 目標（可包括

3、： （ 1）人力與設備費用的節省； （2）處理速度的提高； （3）控制精度和 生產能力的提高； （ 4）管理資訊服務的改進； （5）決策系統的改進； （6）人員工作效 率的提高，等等。 ）3 條件、假定和限制（可包括： （ 1）建議開發軟體運行的最短壽命； （2）進行系統方案 選擇比較的期限； （ 3）經費來源和使用限制； （4）法律和政策方面的限制； （ 5）硬體、 軟體、運行環境和開發環境的條件和限制；（ 6）可利用的資訊和資源； （7）建議開發軟體投入使用的最遲時間。 ）4 可行性研究方法5 決定可行性的主要因素 三對現有系統的分析1處理流程和數據流程2工作負荷3費用支出（如人力、設備、

4、空間、支持性服務、材料等項開支。）4人員（列出所需人員的專業技術類別和數量。）5設備6局限性（說明現有系統存在的問題以及為什麼需要開發新的系統。）四所建議技術可行性分析1對系統的簡要描述2處理流程和數據流程3與現有系統比較的優越性4採用建議系統可能帶來的影響（1）對設備的影響（2）對現有軟體的影響（3）對用戶的影響（4）對系統運行的影響（5）對開發環境的影響（6）對運行環境的影響（7）對經費支出的影響5技術可行性評價（包括： （1）在限制條件下，功能目標是否能夠達到； （ 2）利用現有 技術，功能目標能否達到； （3）對開發人員數量和品質的要求， 並說明能否滿足； （ 4） 在規定的期限內，開

5、發能否完成。 ）五所建議系統經濟可行性分析1指出（1）基建投資（2）其他一次性支出（3）經常性支出2效益（ 1）一次性收益（2）經常性收益（ 3）不可定量收益3收益 / 投資比4投資回收週期5敏感性分析（指一些關鍵性因素，如：系統生存週期長短、系統工作負荷量、處理速 度要求、設備和軟體配置變化對支出和效益的影響等的分析。 ） 六社會因素可行性分析1法律因素（如，合同責任、侵犯專利權、侵犯版權等問題的分析。）2用戶使用可行性（如，用戶單位的行政管理、工作制度、人員素質等能否滿足要求。）七其他可供選擇的方案（逐個闡明其他可供選擇的方案，並重點說明未被推薦的理由。 ） 八結論意見（可能是： （ 1）

6、可著手組織開發； （2）需待若干條件（如資金、人力設備等） 具備後才能開發； （ 3）需對開發目標進行某些修改； （4）不能進行或不必進行 （如技術 不成熟，經濟上不合算等） ；（ 4）其他。）軟體專案計畫（ Software Project Plan ）引言 1編寫目的（闡明編寫軟體計畫的目的，指出讀者對象。）2專案背景（可包括： （1）專案委託單位、開發單位和主管部門； （ 2）該軟體系統與其 他系統的關係。 ）3定義（列出本文檔中用到的專門術語的定義和縮略詞的原文。）4參考資料（可包括： （ 1）專案經核准的計畫任務書、合同或上級機關的批文；（2）文檔所引用的資料、規範等；列出資料的作者

7、、標題、編號、發表日期、出版單位或資 料來源。）專案概述1. 工作內容（簡要說明專案的各項主要工作, 介紹所開發軟體的功能 性能等 . 若不編寫可行性研究報告 , 則應在本節給出較詳細的介紹。 ）2. 條件與限制 （闡明為完成專案應具備的條件 開發單位已具備的條件以及尚需創造的條 件. 必要時還應說明用戶及分合同承包者承擔的工作完成期限及其它條件與限制。 ）3. 產品（ 1）程式（列出應交付的程式名稱使用的語言及存儲形式。 ）（ 2）文檔（列出應交付的文檔。 ）（ 3）運行環境（應包括硬體環境 軟體環境。 ）4服務（闡明開發單位可向用戶提供的服務. 如人員培訓 安裝 保修 維護和其他運行支持。

8、）5驗收標準三實施計畫 1任務分解（任務的劃分及各項任務的負責人。）2進度（按階段完成的專案 , 用圖表說明開始時間 完成時間。） 3預算4關鍵問題（說明可能影響專案的關鍵問題 , 如設備條件 技術難點或其他風險因素 , 並說 明對策。）四人員組織及分工五交付期限六專題計畫要點 （如測試計畫 品質保證計畫 配置管理計畫 人員培訓計畫 系統安裝計畫 等。）需求規格說明書（ Requirements Specification ）一引言1編寫目的（闡明編寫需求說明書的目的 ,指明讀者對象。 ）2 專案背景（可包括： （ 1）專案的委託單位 , 開發單位和主管部門； （2）該軟體系統與 其他系統的關

9、係。 ）3 定義（列出文檔中用到的專門術語定義和縮寫詞的原文。）4 參考資料（可包括： （ 1）專案經核准的計畫任務書 , 合同或上機機關的批文； （2）專 案開發計畫； （3）文檔所引用的資料，標準和規範。列出這些資料的作者、標題、編 號、發表日期、出版單位或資料來源。 ）二任務概述1目標2運行環境3條件與限制三數據描述1 靜態數據2 動態數據（包括輸入數據和輸出數據。 ）3 資料庫描述（給出使用資料庫的名稱和類型。 ）4 數據詞典5 數據採集四功能需求1功能劃分2功能描述五性能需求1數據精確度2時間特性（如回應時間、更新處理時間、數據轉化與傳輸時間、運行時間等。）3適應性（在操作方式 運行

10、環境 與其他軟體的介面以及開發計畫等發生變化時，應具 有的適應能力。 ）六運行需求1用戶介面（如螢幕格式、報表格式、菜單格式、輸入輸出時間等。）2硬體介面3軟體介面4故障處理 七其他需求（如可使用性、安全保密、可維護性、可移植性等。 ）概 要 設 計 說 明 書 ( Architectural Design Specification )一引言1編寫目的（闡明編寫概要設計說明書的目的，指明讀者對象。）2專案背景 （可包括：（1）專案的委託單位 , 開發單位和主管部門； （2）該軟體系統與其 他系統的關係。 ）3定義（列出文檔中用到的專門術語定義和縮寫詞的原意。）4參考資料（列出這些資料的作者、

11、標題、編號、發表日期、出版單位或資料來源，可 包括：（1）專案經核准的計畫任務書，合同或上機機關的批文；（ 2）專案開發計畫；（3）需求規格說明書； （4）測試計畫（初稿） ；（ 5）用戶操作手冊（初稿） ；（6）文檔 所引用的資料、採用的標準或規範。 ）二任務概述1目標2運行環境3需求概述4條件與限制三總體設計1 處理流程2 總體結構和模組外部設計3 功能分配（表明各項功能與程式結構的關係。 ）四介面設計1外部介面（包括用戶介面軟體介面與硬體介面。 ）2內部介面（模組之間的介面。 ）五數據結構設計1 邏輯結構設計2 物理結構設計3 數據結構與程式的關係 六運行設計1運行模組的組合2運行控制3

12、運行時間 七出錯處理設計1出錯輸出資訊2出錯處理對策（如設置後備、性能降級、恢復及再啟動等。 ） 八安全保密設計 九維護設計（說明為方便維護工作的設施, 如維護模組等。 ）詳細設計說明書（ Procedural Design Specification ）一引言1 編寫目的（闡明編寫詳細設計說明書的目的, 指明讀者對象。 ）2 專案背景（應包括專案的來源和主管部門等。）3 定義（列出文檔中用到的專門術語定義和縮寫詞的原意。）4 參考資料（列出這些資料的作者、標題、編號、發表日期、出版單位或資料來源，可 包括：（1）專案的計畫任務書 , 合同或批文； （ 2）專案開發計畫； （3）需求規格說明

13、書；（ 3）概要設計說明書； （ 4）測試計畫 （ 初稿） ；（ 5）用戶操作手冊 （初稿 ） ；（ 5）文 檔所引用的其他資料、軟體開發標準或規範。 ）二總體設計1需求概述2軟體結構（如給出軟體系統的結果圖。 ）三程式描述（逐個模組給出以下的說明 : ：）1功能2性能3輸入專案4輸出專案5演算法（模組所選用的演算法。 ）6 程式邏輯（詳細描述模組實現的演算法，可採用 ：（1）標準流程圖；（2） PDL語言;（3）N-S圖；（4）PAD（ 5）判定表等描述演算法的圖表。）7 .介面&存儲分配9 .限制條件10 .測試要點（給出測試模組的主要測試要求。）用戶操作手冊（ User Guid

14、e ）.引言1編寫目的（闡明編寫手冊的目的，指明讀者對象。）2專案背景（說明專案的來源、委託單位、開發單位及主管部門。）3定義（列出手冊中用到的專門術語定義和縮寫詞的原意。）4參考資料（列出這些資料的作者、標題、編號、發表日期、出版單位或資料來源，可 包括：（1）專案的計畫任務書 ,合同或批文； （ 2）專案開發計畫； （3）需求規格說明書； （ 4）概要設計說明書； （ 5）詳細設計說明書； （6）測試計畫；（ 7）手冊中引用的其他 資料、採用的軟體工程標準或軟體工程規範。 ）二軟體概述1目標2功能3性能（ 1）數據精確度（包括輸入、輸出及處理數據的精度。）（ 2）時間特性（如回應時間、處理

15、時間、數據傳輸時間等。）（ 3）靈活性（在操作方式、運行環境需做某些變更時軟體的適應能力。）三運行環境1硬體（列出軟體系統運行時所需的硬體最小配置，如：（1）電腦型號、 主存容量；（ 2）外存儲器、媒體、記錄格式、設備型號及數量；（ 3）輸入、輸出設備； （4）數據傳輸設備及數據轉換設備的型號及數量。 ）2支持軟體（如： （1）操作系統名稱及版本號； （2）語言編譯系統或彙編系統的名稱及版本號；（ 3）資料庫管理系統的名稱及版本號； （ 4）其他必要的支持軟體。 ） 四使用說明 1安裝和初始化（給出程式的存儲形式、操作命令、回饋資訊及其含義、表明安裝完成 的測試實例以及安裝所需的軟體工具等。

16、）2輸入（給出輸入數據或參數的要求。 ）（ 1）數據背景（說明數據來源、存儲媒體、出現頻度、限制和品質管理等。）（2）數據格式（如： （ 1）長度（ 2）格式基準（ 3）標號（4）順序（ 5）分隔符號（ 6） 辭彙表（ 7）省略和重複（ 8）控制。）（3）輸入舉例3 輸出（給出每項輸出數據的說明。 ）（ 1）數據背景（說明輸出數據的去向、使用頻度、存放媒體及品質管理等。）（2）數據格式（詳細闡明每一輸出數據的格式, 如:首部 主體和尾部的具體形式。 ）（3）舉例3出錯和恢復（給出： （ 1）出錯資訊及其含義（ 2）用戶應採取的措施，如修改、恢復、 再啟動。）4求助查詢（說明如何操作。 ）五運行

17、說明1 運行表 列出每種可能的運行情況 , 說明其運行目的 .2 運行步驟 按順序說明每種運行的步驟 , 應包括 :（ 1） 運行控制（ 2） 操作資訊 （ 1）運行目的 （ 2）操作要求 （3）啟動方法 （ 4）預計運行時間 （ 5） 操作命令格式及說明（ 6）其他事項。 ）（ 3） 輸入 / 輸出檔（給出建立和更新檔的有關資訊，如： （ 1）檔的名稱及編號（ 2） 記錄媒體（ 3）存留的目錄（ 4）檔的支配 說明確定保留檔或廢棄檔的準則， 分發檔的對象，佔用硬體的優先順序及保密控制等。 ）（ 4） 啟動或恢復過程六非常規過程 （提供應急或非常規操作的必要資訊及操作步驟， 如出錯處理操作、

18、向後備 系統切換操作以及維護人員須知的操作和注意事項。 ）七操作命令一覽表（按字母順序逐個列出全部操作命令的格式 功能及參數說明。 ）八程式檔 （或命令檔） 和數據檔一覽表 （按檔案名字母順序或按功能與模組分類順序逐個 列出檔案名稱、識別字及說明。 ）九用戶操作舉例測試計畫（ Test Plan ）一、引言1 編寫目的（闡明編寫測試計畫的目的 , 指明讀者對象。 ）2 專案背景（說明專案的來源委託單位及主管部門。 ）3 定義（列出測試計畫中用到的專門術語定義和縮寫詞的原意。）4 參考資料（列出這些資料的作者、標題、編號、發表日期、出版單位或資料來源，可 包括：（ 1）專案的計畫任務書，合同或批

19、文； （2）專案開發計畫； （3）需求規格說明 書；（ 3）概要設計說明書； （ 4）詳細設計說明書； （ 5）用戶操作手冊 ; g 本測試計畫 中引用的其他資料 採用的軟體開發標準或規範。 ）二任務概述1目標2運行環境3需求概述4條件與限制三計畫1 測試方案（說明確定測試方法和選取測試用例的原則。 ）2 測試專案（列出組裝測試和確認測試中每一項測試的內容、名稱、目的和進度。 ）3 測試準備4 測試機構及人員（測試機構名稱 負責人和職責。 ） 四測試專案說明（按順序逐個對測試專案做出說明： ）1 測試專案名稱及測試內容2 測試用例（ 1）輸入（輸入的數據和輸入的命令。 ）（ 2）輸出（預期的輸

20、出數據。 ）（3）步驟及操作（ 4）允許偏差（給出實測結果與預測結果之間允許偏差的範圍。）3 進度4 條件（給出項測試對資源的特殊要求，如設備、軟體、人員等。）5 測試資料（說明項測試所需的資料。 ）五評價1範圍（說明所完成的各項測試說明問題的範圍及其局限性。）2準則（說明評價測試結果的準則。 ）測試分析報告（ Test Specification ）一引言1編寫目的（闡明編寫測試分析報告的目的，指明讀者對象。）2專案背景（說明專案的來源、委託單位及主管部門。）3 定義（列出測試分析報告中用到的專門術語定義和縮寫詞的原意。）4參考資料（列出這些資料的作者、標題、編號、發表日期、出版單位或資料來

21、源，可 包括：（1）專案的計畫任務書，合同或批文； （2）專案開發計畫； （ 3）需求規格說明 書；（ 4）概要設計說明書； （ 5）詳細設計說明書； （ 6）用戶操作手冊； （ 7）測試計畫； （ 8）測試分析報告所引用的其他資料、採用的軟體工程標準或軟體工程規範。）二測試計畫執行情況1測試專案（列出每一測試專案的名稱、內容和目的。）2測試機構和人員（給出測試機構名稱、負責人和參與測試人員名單。）3測試結果（按順序給出每一測試專案的： （ 1）實測結果數據（ 2）與預期結果數據的偏 差（ 3）該項測試說明的事實（ 4）該項測試發現的問題。 ）三軟體需求測試結論 （按順序給出每一項需求測試的結論。包括：（1）證實的軟體能力 （ 2）局限性（即項需求未得到充分測試的情況及原因） 。）四評價1軟體能力（經過測試所表明的軟體能力。 ）2缺陷和限制（說明測試所揭露的軟體缺陷和不足, 以及可能給軟體運行帶來的影響。 ）3建議（提出為彌補上述缺陷的建議。 ）4測試結論（說明能否通過。 ）開 發 進 度 表