軟件文檔審查方法及工程實(shí)踐

王海明 鄧艷秀 李曉婷

（1.工業(yè)和信息化部電子第五研究所 廣東省廣州市 510610 2.廣州現(xiàn)代信息工程職業(yè)技術(shù)學(xué)院 廣東省廣州市 510670）

1 引言

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

2 文檔審查范圍和內(nèi)容

文檔審查是對(duì)委托方提交的文檔的一致性、完整性和準(zhǔn)確性所進(jìn)行的檢查。文檔審查應(yīng)確定審查所用的檢查單，為適應(yīng)不同的文檔審查，需要用不同的檢查單，檢查單應(yīng)經(jīng)過由委托方組織的外部評(píng)審。

在軟件開發(fā)過程中可產(chǎn)生系統(tǒng)/子系統(tǒng)規(guī)格說明、系統(tǒng)/子系統(tǒng)設(shè)計(jì)說明、軟件開發(fā)計(jì)劃、軟件研制任務(wù)書、軟件需求規(guī)格說明等文檔，這些配套文檔按照用途可分為開發(fā)類、管理類、測(cè)試類、維護(hù)類等。軟件開發(fā)配套文檔分類如表1所示。

表1：軟件開發(fā)配套文檔分類

文檔審查范圍應(yīng)根據(jù)用戶要求、合同、測(cè)評(píng)方案或其他等效文件綜合確定[1]，一般包括系統(tǒng)/子系統(tǒng)規(guī)格說明、系統(tǒng)/子系統(tǒng)設(shè)計(jì)說明、軟件開發(fā)計(jì)劃、軟件研制任務(wù)書、軟件需求規(guī)格說明、軟件設(shè)計(jì)說明等開發(fā)類文檔。這些開發(fā)類文檔是軟件開發(fā)過程產(chǎn)生的主要技術(shù)文檔，也是軟件第三方測(cè)評(píng)的重要依據(jù)，因此需重點(diǎn)從文檔的完整性、規(guī)范性、一致性、準(zhǔn)確性四個(gè)方面進(jìn)行審查：

2.1 文檔的完整性審查

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

（2）是否符合相關(guān)標(biāo)準(zhǔn)要求的內(nèi)容和格式；

（3）文檔對(duì)接收、處理的數(shù)據(jù)描述是否完整。

2.2 文檔的規(guī)范性審查

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

（2）是否有專業(yè)術(shù)語解釋、圖形顯示以及相關(guān)的注釋。

2.3 文檔的一致性審查

（1）審查縮略語和內(nèi)容前后是否統(tǒng)一；

（2）檢查文文間、文實(shí)間的一致性。

2.4 文檔的準(zhǔn)確性審查

（1）內(nèi)容是否正確、準(zhǔn)確；

（2）是否有錯(cuò)別字；

（3）術(shù)語、定義或內(nèi)容是否有歧義。

對(duì)于軟件測(cè)試計(jì)劃、軟件測(cè)試說明、軟件測(cè)試報(bào)告、軟件配置管理計(jì)劃等測(cè)試類、管理類和維護(hù)類文檔主要審查文檔的完整性和規(guī)范性。

3 文檔審查依據(jù)和過程

3.1 文檔審查依據(jù)

文檔審查不只需要審查文檔的格式，還需要審查文檔內(nèi)容的準(zhǔn)確性和一致性。對(duì)于文檔的格式規(guī)范性的審查可依據(jù)相關(guān)標(biāo)準(zhǔn)，這些標(biāo)準(zhǔn)通常規(guī)定了軟件開發(fā)過程中產(chǎn)生的文檔的要求，并以附錄的形式給出了各類軟件文檔的章節(jié)架構(gòu)和正文格式要求，研制單位可根據(jù)上級(jí)要求、任務(wù)書等，確定產(chǎn)生具體軟件文檔類別，對(duì)相關(guān)文檔進(jìn)行重組或裁剪[2]。 對(duì)于文檔內(nèi)容的準(zhǔn)確性和一致性的審查，可依據(jù)型號(hào)的合同、工程實(shí)施方案等頂層需求及第三方測(cè)試要求來開展文檔審查。

3.2 文檔審查過程

文檔審查通常在三方測(cè)試靜態(tài)測(cè)試階段進(jìn)行，文檔審查過程如圖1所示。

圖1：文檔審查過程

文檔審查主要包括以下幾個(gè)步驟：

3.2.1 制定文檔審查單

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

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

3.2.2 審查文檔及填寫記錄

測(cè)試單位測(cè)試人員對(duì)照文檔審查單逐項(xiàng)對(duì)被測(cè)軟件配套文檔進(jìn)行審查，主要審查文檔的完整性、規(guī)范性、一致性、準(zhǔn)確性，并填寫文檔審查單記錄。

3.2.3 填寫軟件文檔審查問題報(bào)告

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

表3：軟件文檔審查問題報(bào)告單

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

研制單位根據(jù)測(cè)試單位提交的文檔審查問題報(bào)告對(duì)軟件文檔進(jìn)行修改，對(duì)修改后等文檔升級(jí)入庫(kù)，并填寫軟件文檔審查問題處理報(bào)告，文檔審查問題處理報(bào)告應(yīng)包括問題標(biāo)識(shí)、文檔種類、處理版本、問題處理描述、處理人、處理時(shí)間等信息。表4為軟件文檔審查問題處理報(bào)告單示例。

表4：軟件文檔審查問題處理報(bào)告單

3.2.5 文檔審查回歸測(cè)試

測(cè)試單位根據(jù)研制單位提交的文檔審查問題處理報(bào)告，對(duì)修改后的文檔進(jìn)行文檔審查回歸測(cè)試，確認(rèn)文檔審查測(cè)試過程中發(fā)現(xiàn)問題是否閉環(huán)，若所有問題均閉環(huán)且未引用新的問題，則結(jié)束；若存在問題未閉環(huán)或引入新的問題，則重復(fù)步驟3.2.2，直至所有問題閉環(huán)。

3.2.6 軟件文檔評(píng)估和總結(jié)

測(cè)試單位根據(jù)文檔審查過程和記錄出具文檔審查測(cè)試報(bào)告，測(cè)試報(bào)告中應(yīng)詳細(xì)描述文檔審查的測(cè)試過程、測(cè)試中發(fā)現(xiàn)的問題及處理情況、軟件文檔版本變化情況等，并對(duì)軟件文檔質(zhì)量從以下幾方面進(jìn)行評(píng)價(jià)：軟件文檔是否齊套；軟件文檔編制格式的規(guī)范性是否覆蓋相關(guān)標(biāo)準(zhǔn)要求；軟件文檔是否文文一致，具有可追溯性；文檔標(biāo)識(shí)和簽署是否完備。

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

4.1 文檔完整性審查方法

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

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

4.2 文檔規(guī)范性審查方法

對(duì)文檔規(guī)范性審查通常依據(jù)文檔審查檢查單和相關(guān)標(biāo)準(zhǔn)對(duì)文檔的格式、章節(jié)等進(jìn)行審查。

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

4.3 文檔一致性審查方法

文檔一致性包括文文間一致性和上下文一致性，所以需重點(diǎn)對(duì)文檔間、上下文相關(guān)或相同內(nèi)容進(jìn)行比對(duì)審查。如系統(tǒng)規(guī)格說明文檔和頂層要求之間的一致性、軟件需求規(guī)格說明文檔和軟件研制任務(wù)書文檔之間的一致性、軟件設(shè)計(jì)說明文檔和軟件需求規(guī)格說明文檔之間的一致性等。

常見的文檔一致性問題：軟件需求規(guī)格說明和軟件研制任務(wù)書相同內(nèi)容描述不一致；軟件需求規(guī)格說明上下文相關(guān)內(nèi)容描述不一致；文檔中接口圖和接口表的描述不一致；文檔追溯表章節(jié)號(hào)與實(shí)際章節(jié)不一致等。

4.4 文檔準(zhǔn)確性審查方法

文檔準(zhǔn)確性審查通常審查文檔描述是否準(zhǔn)確無歧義，重點(diǎn)審查文檔的功能、性能和接口描述等內(nèi)容是否準(zhǔn)確唯一。

常見的文檔準(zhǔn)確性問題：文檔功能需求描述不具體，不具有驗(yàn)證性；文檔中數(shù)據(jù)缺少單位；文檔中軟件運(yùn)行環(huán)境或開發(fā)工具缺少版本等。

5 文檔審查工具及應(yīng)用

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

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

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

圖3：導(dǎo)入文檔模板

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

圖4：文檔檢查工具文檔審查結(jié)果

文檔檢查工具支持對(duì)軟件需求規(guī)格說明、軟件設(shè)計(jì)說明、軟件研制總結(jié)等的文檔與標(biāo)準(zhǔn)的一致性檢查功能，支持對(duì)章節(jié)、標(biāo)題、內(nèi)容、表格等字體的格式、文檔段落進(jìn)行縮進(jìn)、圖表順序進(jìn)行一致性檢查，支持文檔追溯關(guān)系正確性檢查。通過文檔檢查工具可有效提供文檔審查工作的全面性和效率，在復(fù)雜系統(tǒng)文檔眾多的情況下，文檔檢查工具的作用尤為明顯。

6 結(jié)語

文檔審查作為軟件第三方測(cè)試的一項(xiàng)重要工作內(nèi)容，是提升軟件文檔質(zhì)量的一項(xiàng)重要舉措。本文系統(tǒng)介紹了軟件文檔審查的范圍和內(nèi)容，文檔審查依據(jù)和過程，并分別從文檔的完整性、規(guī)范性、一致性、準(zhǔn)確性四個(gè)方面介紹了審查方法和常見典型問題，最后介紹了文檔審查工具及工程實(shí)踐，可為軟件測(cè)試人員進(jìn)行文檔審查實(shí)踐提供參考。