论文阅读Usage and usefulness of technical software documentation An industrial技术软件文档的使用和有用性: 一个工业案例研究

技术软件文档的使用和有用性: 一个工业案例研究

a b s t r a c t

目的:我们旨在更好地了解使用和各种技术文件的有效性在软件开发和维护。

方法:我们利用以前系统制图研究的结果，并在NovAtel进行工业案例研究。从分析目标的共同定义出发，本研究方法结合了对55份文件(与设计、试验和过程有关的)和1630份文件的修订进行定性和定量分析。此外，我们还对文件的使用和有用性进行了调查。来自行业合作伙伴的共有25名工作人员参加了这次调查，他们都具有中等至高水平的经验。

结果:(1)技术文档最不常用于维护目的，而最常用于开发的信息源，(2)源代码被认为是最常作为首选信息源在软件维护,(3)在开发和维护之间没有显著差异的使用不同的文档类型,(4)初始假设说明最新信息,精度和准确性是技术文档中影响效用最高的。

结论:根据不同的目的，文档的使用是不同的，它取决于信息需求的类型以及要完成的任务(例如，开发和维护)。

---

1. Introduction and motivation

   本文研究的技术软件文档：需求规范，设计(架构)文档，对源代码的评论，测试文档和过程描述。

   本文的主要研究成果有:

   （1）一种经验的方法，包括定量的和定性的评估文件和他们的修订，以评估技术软件文件的使用和有用性。

   （2）对文件的使用及其与其他因素(如文件类型、工作功能、经验程度和可读性)的关系进行评估和确证性分析。

   （3）对文档有用性的探索性分析。

   （4）基于分析的文件编制和开发流程的改进指南

2. Background and related work

   2.1. Technical documentation

   (1)论文重点:50篇论文关注文档质量，37篇论文关注收益，12篇论文关注文档成本，(2)在大多数论文中出现的文档的质量属性是:完整性、一致性和可访问性。

   我们发现，文献成本方面在现有的文献中似乎被忽视了，并且没有系统的方法或模型来衡量成本。

   2.2. Usage of technical documentation

   在本文中，我们研究了文档类型和可读性如何影响其使用。

   总的来说，我们的研究集中在两个阶段的文档工件的使用:

   （1）在开发周期中的使用:在需求、设计和编码阶段

   （2）开发后(维护期间)的使用:这个阶段调查bug修复(纠正性维护)和特性添加(添加性维护)活动。

   2.3. Usefulness of technical documentation

   文档工件的有用性被描述为:“对文档内容能够提供知识、信息和/或对其读者的洞察力的度量，这些知识、信息和/或洞察力与其他可用工件有关，考虑到工件的活动和价值。”

   2.4. Modelling of documentation usage and usefulness

   在rq3中，我们将使用成本效益和感知有用性作为技术文档有用性的两个衡量标准。

3. Research methodology and case-study design

   我们的研究方法是案例研究的确认性、描述性和探索性相结合的方法。

   描述部分描述了案例研究公司的现状，并应用于文档的使用。

   解释部分是寻找影响因素部分已知的文献和认为相关的公司背景。

   最后，我们的探索性研究部分着眼于正在发生的事情并寻求新的见解。

   3.2. Research questions

   rq1 -技术软件文档的使用特性

   RQ 1.1(信息源):与其他信息源相比，技术文档的使用频率是多少?例如，与团队成员的沟通，对代码文档的引用，以及开发人员现有的(自身的)知识。

   RQ 1.2(开发vs维护):文件状态的使用在开发和维护阶段有区别吗?

   rq2 -影响文档使用的因素

   RQ 2.1(文档类型):文档类型对其使用有显著影响吗?例如，与设计文档相比，对require文档的访问是否更频繁?

   RQ 2.2(工作功能):专业人员的角色对文档使用水平有重大影响吗?例如，测试人员使用文档是否更多于开发人员?

   RQ 2.3(经验程度):经验对文档使用的水平有显著的影响吗?有多年经验的工程师使用文档的少吗?

   RQ 2.4(可读性):文档的可读性对文档的使用水平有显著的影响吗?

   rq3-技术文档的有用性

   RQ 3.1:如何确定文件的成本效益?

   RQ 3.2:技术文档的有用性是什么?

   3.3. Research approach

   我们的实际案例研究可以描述为六个主要步骤:

   第一步:定义范围和上下文

   第二步:案例研究设计

   第三步:数据收集

   第四步:调查

   第五步:数据分析

   第六步:报告和结论

   3.4. Case-study design and data collection
   3.4.1. Definition of scope and context

   3.4.2. Data collection

   注意，在公司中，代码注释不是存储在DSTS中，而是嵌入到存储在源代码版本控制系统中的源代码文件中。

   3.4.3. Questionnaire-based survey

   调查的主要方面涉及:

   （1）参与者的人口统计资料和经验相关的问题。

   （2）设计了一些人口统计学问题来筛选受访者，并根据他们的职位和软件领域的经验来帮助区分不同的人。这些问题是关于被调查者的特点和环境的。

   （3）文档的感知质量与潜力(预期)文件质量。

   （4）在软件开发和维护过程中负责文档编制工作。

   （5）为开发和维护的目的，对文档工件的当前使用有很大的帮助。

   （6）在开发和维护活动中对文档的感知。

   （7）有关于参与者在开发和维护活动中对不同类型文档的个人使用和偏好，以及关于这些文档工件的有效性的意见。

   3.4.4. Selection of the product under study

   选择OEM6作为所研究的软件产品，将存储在DSTS文档管理系统中的60000个文档压缩到几百个。然后我们应用集群和随机抽样从OEM6的SDLC的所有阶段中选择最具代表性的文档。

   我们选择了20个概念设计文件作为案例研究，涵盖了论文的主要模块 OEM6嵌入式软件，15个测试文档和20个软件过程文档。

   3.4.5. Data analysis methods

   所有RQ、子RQ、分析目标、相应的假设和每个RQ应用的分析方法的概述(如表4所示)。

   对于统计推断分析，我们应用了非参数检验(Mann-Whitney, Kruskal-Wallis)，因为我们不能确定潜在总体遵循正态分布。

   RQ	sub-RQ	Goals of analysis, treatments and corresponding hypotheses
   RQ 1 – Analysis of usage of technical documentation	RQ 1.1(每个信息源的使用量) RQ 1.2(每个阶段使用)	- H0(1,1a):在开发过程中使用技术文档与使用源代码的对比验证试验(盒形图和Mann-Whitney U测试) - H0(1,1b):在维护期间使用技术文档与使用源代码 - H0(1,1c):在开发过程中使用技术文档与个人交流 - H0(1,1d):在维护期间使用技术文件与个人沟通 - H0(1,1e):在开发过程中使用技术文档和个人知识 - H0(1,1f):在维护过程中使用技术文档和个人知识 - H0(1,2):在开发和维护期间使用技术文档
   RQ 2 – Factors impacting documentation usage	RQ 2.1(文件类型) RQ 2.2(工作职能) RQ 2.3 (Information usage for varying degree of experience) RQ 2.4 (Documentation type usage for varying degree of experience) RQ 2.5 (Readability)	- H0(2,1a):在开发过程中使用各种类型的技术文档 - H0(2,1b):在维护期间使用各种类型的技术文件 - H0(2,2a):在开发过程中为不同的工作职能使用技术文档探索(框图) - H0(2,2b):在各种工作功能的维护期间使用技术文件 - H0(2,3a):对开发过程中不同程度经验的信息类型的使用验证试验(箱形图和Mann-Whitney测试) - H0(2,3b):在维护过程中使用不同程度的经验类型的信息 - H0(2,4a):对开发过程中不同程度的经验使用文档类型验证性试验(箱形图和Kruskal-Wallis试验) - H0(2,4b):使用文档类型，用于维护期间不同程度的经验 文档的可读性对其使用的影响
   RQ 3 – Analysis of usefulness	RQ 3.1 (Cost effectiveness) RQ 3.2 (Perceived usefulness)	分析潜在影响成本效率指数和文档访问次数的因素的相关性。 技术文件的可用性。

4. Results

   4.1. RQ 1 – analysis of usage

   4.1.1. RQ 1.1 – usage of documentation in comparison of other sources of information

   基于上述讨论，我们发现开发和维护目的之间文档的使用略有不同。我们的结果与现有的文献是一致的，例如，[20,32]，因为源代码是在维护期间研究的最常用的工件。

   4.1.2. RQ 1.2 – usage of documentation in development versus maintenance

   在软件开发和维护活动期间文档的使用没有显著的区别。

   4.2. RQ 2 – factors influencing documentation usage

   4.2.1. RQ 2.1 – usage of documentation for varying document types

   在开发阶段使用最多的文档工件是设计文档。类似地，代码注释是用于维护目的的最常用的文档工件。

   4.2.2. RQ 2.2 – usage of documentation in dependence of job function

   4.2.3. RQ 2.3 – usage of source of information in dependence of the degree of experience

   4.2.4. RQ 2.4 – usage of documentation type in dependence of the degree of experience

   设计文件大多被从业者在职业生涯的早期使用(长达5年的费用)。

   4.2.5. RQ 2.5 – impact of readability and usage

   4.3. RQ 3 – analysis of usefulness

   我们从两个角度探讨有用性的表征。首先，以自动化测量为基础，将成本效益作为有用性的一个重要方面进行了研究。其次，我们看一下影响有用性的各个方面，并分析案例研究项目上下文的现有差距。

   4.3.1. RQ 3.1 – characterize the cost-effectiveness of documents?

   4.3.2. RQ 3.2 – perceived usefulness of technical documentation

5. Discussions and Interpretation of findings

   5.1. Summary of the findings and interpretations of the findings

   在RQ 1.1的结果中，我们发现在维护期间对源代码的使用远远超过对技术文档的使用。RQ 1.2的结果显示，在软件开发期间文档的使用比在维护阶段更多。

   RQ2探索了在开发和维护阶段影响文档使用的各种因素。RQ 2.1的结果显示，在开发阶段，最密集使用的文档工件是设计文档，然而，出于维护目的，代码注释扮演着最密集使用的文档工件的角色。RQ2.2我们从方框图中看到，在某种程度上，中级开发人员比高级开发人员使用更多的文档。RQ 2.3我们观察到(从方框图中)，在某种程度上，有更多经验的开发人员倾向于使用更少的文档，这是人们所期望的。RQ 2.4 我们观察到，开发人员的经验对开发或维护期间使用的文档类型没有任何重大影响。RQ 2.5 我们发现设计文档的可读性和它们的使用之间存在着微弱的正相关关系。

   RQ3探索并分析了文档的有用性。RQ3.1文档越大(按单词数量计算)，CEI(成本效益)就越低，这表示开发的(额外的)大型文档可能没有那么高的成本效益。RO 3.2 从参与者的角度来看，最相关的因素是影响高质量的因素文档包括文档的最新性、内容的相关性、准确性和文档的严谨性。其他重要因素包括文档的完整性、可视化模型和准确性。相反，文档技术被认为是最不相关的因素。

   5.2. Challenges and lessons learned

   该项目的主要技术挑战是研究结果:以定量的方式客观地测量数据的使用并不是一件小事。

   该项目的主要非技术挑战如下:确保所有涉众的参与并保持他们的研究动机水平，特别是案例研究公司的大型软件工程师团队，并不是一件容易的事。我们观察到在短期和长期研究计划方面略有不同。学术研究者和实践者使用了稍微不同的术语.

6. Recommendations for improvement of documentation process in the Industrial Context

   根据RQ 1.1的输出，我们发现在维护期间使用源代码本身和代码注释要比使用文档重要得多。

   因此，我们建议文档主要为开发目的而不是维护目的准备和定位，并且软件工程师团队要相应地准备文档。

   因此，我们建议软件工程团队确保设计文件的及时和高质量。

   因此，我们建议在准备文档时考虑中间开发人员的需求。

   因此，我们建议提高文档的可读性。

   因此，我们建议避免创建超大文档。

   影响文件质量的重要质量属性有:文件的及时性、内容的相关性、准确性和文件的精确性。因此，我们向软件工程师团队建议，提高文档质量的改进机会应该集中在这些因素上。

7. Applicability of the results

   所有其他研究成果都在影响决策过程，以改善整个过程。重点包括:确定文档的受众和它的生命周期(在设计、测试、维护期间，或者只是其中之一，等等)，确定高级文档树，并为特定主题创建更小的下级文档，以便每个文档尽可能小(模块化文档)。

8. Threats to validity

   8.1. Construct validity

   The construct validity issue in this case study is related to what extent the selected documentation usage and usefulness metrics really represent what we intended to measure. Another threat to construct validity is the measurement of documentation usefulness attributes.

   8.2. External validity

   The issue of external validity concerns whether the results of the case study can be generalized beyond this specific study context.

   8.3. Internal validity

   Internal validity reflects the extent to which a causal conclusion based on a study is warranted（证实）.

   8.4. Conclusion validity

   Threats to conclusion validity refer to the ability to draw correct conclusions about the relations between the treatment and the outcome of an experiment

9. Conclusion and future work

(1)在维护任务期间，源代码被认为是最频繁的文档来源;

(2)在维护活动期间，技术文档被认为是使用频率最低的，而其最频繁的是作为开发活动的信息源;

(3)在开发和维护过程中，需求文档、设计文档、代码注释文档、测试文档和过程文档等各类文档的使用没有显著差异;

(4)可读性对技术文档使用的影响较小;

(5)一些最初的假设表明，最新性和精确性对技术文档的有用性影响最大。