软件文档审查方法及工程实践

2021-03-08王海明邓艳秀李晓婷

电子技术与软件工程 2021年23期

王海明邓艳秀李晓婷

（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：文档检查工具文档审查结果

文档检查工具支持对软件需求规格说明、软件设计说明、软件研制总结等的文档与标准的一致性检查功能，支持对章节、标题、内容、表格等字体的格式、文档段落进行缩进、图表顺序进行一致性检查，支持文档追溯关系正确性检查。通过文档检查工具可有效提供文档审查工作的全面性和效率，在复杂系统文档众多的情况下，文档检查工具的作用尤为明显。