軟件文檔審查方法及工程實踐

王海明 鄧艷秀 李曉婷

（1.工業和信息化部電子第五研究所 廣東省廣州市 510610 2.廣州現代信息工程職業技術學院 廣東省廣州市 510670）

1 引言

隨著我國信息技術的突飛猛進，軟件的復雜程度和規模逐年遞增，軟件不僅包括代碼，通常也包括軟件配套文檔。軟件開發配套文檔是研制單位開發和測試單位后續開展軟件測試的重要輸入依據，也是維保人員進行軟件維護的重要參考，軟件配套文檔的詳細程度和質量會對后續軟件開發、測試和維護均有重大影響；同時軟件開發配套文檔是產品鑒定定型的重要備查材料，文檔是否齊全及好壞將直接影響產品鑒定定型流程。軟件測評是用戶或研制單位委托第三方測試機構在規定的條件下對程序進行操作，以發現程序錯誤，衡量軟件質量，評估其是否能滿足設計要求。軟件測評作為保障軟件質量的重要手段，其中文檔審查就是軟件測評當中的一項主要工作內容，具有十分重要的作用。下面分別從文檔審查范圍和內容、文檔審查依據和過程、文檔審查方法和典型問題等幾方面來系統介紹文檔審查。

2 文檔審查范圍和內容

文檔審查是對委托方提交的文檔的一致性、完整性和準確性所進行的檢查。文檔審查應確定審查所用的檢查單，為適應不同的文檔審查，需要用不同的檢查單，檢查單應經過由委托方組織的外部評審。

在軟件開發過程中可產生系統/子系統規格說明、系統/子系統設計說明、軟件開發計劃、軟件研制任務書、軟件需求規格說明等文檔，這些配套文檔按照用途可分為開發類、管理類、測試類、維護類等。軟件開發配套文檔分類如表1所示。

表1：軟件開發配套文檔分類

文檔審查范圍應根據用戶要求、合同、測評方案或其他等效文件綜合確定[1]，一般包括系統/子系統規格說明、系統/子系統設計說明、軟件開發計劃、軟件研制任務書、軟件需求規格說明、軟件設計說明等開發類文檔。這些開發類文檔是軟件開發過程產生的主要技術文檔，也是軟件第三方測評的重要依據，因此需重點從文檔的完整性、規范性、一致性、準確性四個方面進行審查：

2.1 文檔的完整性審查

（1）文檔是否齊套，是否與要交付的文檔清單一致；

（2）是否符合相關標準要求的內容和格式；

（3）文檔對接收、處理的數據描述是否完整。

2.2 文檔的規范性審查

（1）文檔的格式、圖表等排版是否規范；

（2）是否有專業術語解釋、圖形顯示以及相關的注釋。

2.3 文檔的一致性審查

（1）審查縮略語和內容前后是否統一；

（2）檢查文文間、文實間的一致性。

2.4 文檔的準確性審查

（1）內容是否正確、準確；

（2）是否有錯別字；

（3）術語、定義或內容是否有歧義。

對于軟件測試計劃、軟件測試說明、軟件測試報告、軟件配置管理計劃等測試類、管理類和維護類文檔主要審查文檔的完整性和規范性。

3 文檔審查依據和過程

3.1 文檔審查依據

文檔審查不只需要審查文檔的格式，還需要審查文檔內容的準確性和一致性。對于文檔的格式規范性的審查可依據相關標準，這些標準通常規定了軟件開發過程中產生的文檔的要求，并以附錄的形式給出了各類軟件文檔的章節架構和正文格式要求，研制單位可根據上級要求、任務書等，確定產生具體軟件文檔類別，對相關文檔進行重組或裁剪[2]。 對于文檔內容的準確性和一致性的審查，可依據型號的合同、工程實施方案等頂層需求及第三方測試要求來開展文檔審查。

3.2 文檔審查過程

文檔審查通常在三方測試靜態測試階段進行，文檔審查過程如圖1所示。

圖1：文檔審查過程

文檔審查主要包括以下幾個步驟：

3.2.1 制定文檔審查單

測試單位需針對不同類型文檔制定不同的文檔審查單，如系統規格說明審查單、軟件研制任務書審查單、軟件需求規格說明審查單、軟件設計文檔審查單、其他通用文檔審查單等。文檔審查單通常應包括軟件名稱、研制單位、審查人、檢查日期、審查條目、合格/不合格/不適用等。文檔審查單一般附在測評大綱中，并隨測評大綱一起通過用戶組織的外部評審。一種典型的文檔審查單如表2所示。

表2：軟件文檔審查檢查單

3.2.2 審查文檔及填寫記錄

測試單位測試人員對照文檔審查單逐項對被測軟件配套文檔進行審查，主要審查文檔的完整性、規范性、一致性、準確性，并填寫文檔審查單記錄。

3.2.3 填寫軟件文檔審查問題報告

在文檔審查過程中若有文檔審查單條目存在不通過的情況，則測試單位需填寫文檔審查問題報告，并將文檔審查問題報告提交研發人員，文檔審查問題報告應包括文檔標識、文檔種類、版本、問題描述、問題類型、問題等級、問題提交人、提交時間等信息。表3為軟件文檔審查問題報告單示例。

表3：軟件文檔審查問題報告單

3.2.4 研制單位修改文檔并填寫文檔審查問題處理報告

研制單位根據測試單位提交的文檔審查問題報告對軟件文檔進行修改，對修改后等文檔升級入庫，并填寫軟件文檔審查問題處理報告，文檔審查問題處理報告應包括問題標識、文檔種類、處理版本、問題處理描述、處理人、處理時間等信息。表4為軟件文檔審查問題處理報告單示例。

表4：軟件文檔審查問題處理報告單

3.2.5 文檔審查回歸測試

測試單位根據研制單位提交的文檔審查問題處理報告，對修改后的文檔進行文檔審查回歸測試，確認文檔審查測試過程中發現問題是否閉環，若所有問題均閉環且未引用新的問題，則結束；若存在問題未閉環或引入新的問題，則重復步驟3.2.2，直至所有問題閉環。

3.2.6 軟件文檔評估和總結

測試單位根據文檔審查過程和記錄出具文檔審查測試報告，測試報告中應詳細描述文檔審查的測試過程、測試中發現的問題及處理情況、軟件文檔版本變化情況等，并對軟件文檔質量從以下幾方面進行評價：軟件文檔是否齊套；軟件文檔編制格式的規范性是否覆蓋相關標準要求；軟件文檔是否文文一致，具有可追溯性；文檔標識和簽署是否完備。

4 文檔審查方法和典型問題

4.1 文檔完整性審查方法

文檔完整性審查根據型號要求制定文檔審查檢查列表并隨測評大綱通過外部評審，然后依據測評大綱中文檔審查列表檢查研制單位提交的被測文檔是否齊全，同時審查文檔描述是否完整，軟件的功能、性能、接口等是否有遺漏。完整性檢查通常包含需求規格、軟件接口需求、軟件設計文檔、軟件使用手冊等文檔的完整性檢查。完整性檢查包含標識、引用文檔、CSCI內部接口需求、系統的內部接口需求、安全性需求等眾多檢查項目；除此以外，完整性檢查模塊還包含需求可追蹤性檢查、引用文檔檢查、特定檢查項目（如：安全性需求、保密性需求、驗收、交付和包裝需求、需求可追蹤性）。

常見的文檔完整性問題：關鍵等級軟件缺少軟件失效分析報告；帶界面類軟件缺少軟件用戶手冊；嵌入式軟件缺少固件保障手冊；軟件需求規格說明文檔未能覆蓋軟件研制任務書中的全部性能指標；看門狗功能描述缺少喂狗時間和復位時間；自檢功能描述缺少自檢時間；文檔追溯表缺少逆向追溯等。

4.2 文檔規范性審查方法

對文檔規范性審查通常依據文檔審查檢查單和相關標準對文檔的格式、章節等進行審查。

常見的文檔規范性問題：文檔的章節與相關標準要求的章節不一致，且不適用章節無特別說明；文檔中圖、表序號未按照順序編號或不符合編號規則；文檔缺少版本、目錄未更新、索引找不到等問題。

4.3 文檔一致性審查方法

文檔一致性包括文文間一致性和上下文一致性，所以需重點對文檔間、上下文相關或相同內容進行比對審查。如系統規格說明文檔和頂層要求之間的一致性、軟件需求規格說明文檔和軟件研制任務書文檔之間的一致性、軟件設計說明文檔和軟件需求規格說明文檔之間的一致性等。

常見的文檔一致性問題：軟件需求規格說明和軟件研制任務書相同內容描述不一致；軟件需求規格說明上下文相關內容描述不一致；文檔中接口圖和接口表的描述不一致；文檔追溯表章節號與實際章節不一致等。

4.4 文檔準確性審查方法

文檔準確性審查通常審查文檔描述是否準確無歧義，重點審查文檔的功能、性能和接口描述等內容是否準確唯一。

常見的文檔準確性問題：文檔功能需求描述不具體，不具有驗證性；文檔中數據缺少單位；文檔中軟件運行環境或開發工具缺少版本等。

5 文檔審查工具及應用

目前文檔審查工作通常由人工對照軟件文檔進行審查，非常耗時且效率低下，市面上文檔審查工具也比較少見。其中DocTrack文檔檢查工具是一款非常出色的文檔審查工具，DocTrack文檔檢查工具能夠對文檔格式、規范、字體等各方面進行全面審查，暴露文檔編寫中出現的各種問題，從而提升項目或軟件產品的質量，提高軟件研制工作效率。圖2為DocTrack文檔檢查工具主界面圖。

圖2：DocTrack文檔檢查工具主界面

在使用DocTrack文檔檢查工具進行文檔審查前需先建立各類文檔的模板，然后將模板導入到檢查工具，如圖3所示。

圖3：導入文檔模板

將被測軟件配套文檔導入到DocTrack文檔檢查工具，設置自定義文檔檢查規則及文檔章節的匹配層級，然后使用文檔檢查工具對文檔進行分析，可以得到文檔審查結果，并以列表的形式給出文檔格式問題、規范性問題、內容問題等。圖4所示為使用文檔檢查工具對軟件需求規格說明進行文檔檢查結果。

圖4：文檔檢查工具文檔審查結果

文檔檢查工具支持對軟件需求規格說明、軟件設計說明、軟件研制總結等的文檔與標準的一致性檢查功能，支持對章節、標題、內容、表格等字體的格式、文檔段落進行縮進、圖表順序進行一致性檢查，支持文檔追溯關系正確性檢查。通過文檔檢查工具可有效提供文檔審查工作的全面性和效率，在復雜系統文檔眾多的情況下，文檔檢查工具的作用尤為明顯。

6 結語

文檔審查作為軟件第三方測試的一項重要工作內容，是提升軟件文檔質量的一項重要舉措。本文系統介紹了軟件文檔審查的范圍和內容，文檔審查依據和過程，并分別從文檔的完整性、規范性、一致性、準確性四個方面介紹了審查方法和常見典型問題，最后介紹了文檔審查工具及工程實踐，可為軟件測試人員進行文檔審查實踐提供參考。