软件文档问题揭露

1. 简介

为了克服这些限制，我们定性分析了来自各种数据源的不同类型的工件，并确定了开发人员在处理文档时面临的问题。具体来说，我们挖掘了开源软件存储库，并检查了与开发电子邮件，编程论坛讨论，问题和与软件文档相关的拉取请求相对应的 878 个工件。对于每个工件，我们确定了所 告的问题，呈现该问题的文档的类型，所提出的解决方案以及所讨论的文档工具。根据我们的分析，我们建立了一个由 162 种文档问题组成的综合分类法，这些文档问题与（i）其中包含的信息，（ii）信息的呈现方式，（iii）文档过程和（iv）文档工具支持相关。我们描述并举例说明每种类别的文档问题。我们还将讨论它们在软件研究和实践中的含义，并得出解决这些问题所需的可行措施。

2. 实证研究设计

我们的目标是回答以下研究问题（RQ）：开发人员面临哪些文档问题？

A 数据收集

在此最终过程中，丢弃了 5 个工件作为误 。表 II 告了为每种工件标记的句子的最终数量。

B 数据分析

我们通过给出分析中发现的文档问题类型的分类法来回答我们的 RQ。

3. 结果讨论

为标记过程的结果，我们获得了 824 个工件，包括总共 1,548 个标记的句子。

我们确定的 162 个文档问题类型的分层分类分为四个主要类别：（i）与文档的信息内容有关的问题描述了由文档中“内容”引起的问题； （ii）分类在信息内容（如何）类别下的问题集中于“如何”编写和组织内容； （iii）与过程相关的类别将与文档过程相关的问题分组； （iv）与工具有关的事项源于使用文档工具。请注意，单个工件可能会讨论多种类型的问题。

接下来，对于每个类别，我们将描述代表性示例，并讨论从我们的发现中得出的结论对研究人员和/或从业人员的意义。

A 信息内容（What）

共有 485 个工件讨论与信息内容相关的问题，即文档中写的是“What”。

正确性（72）。正确的文档会根据事实提供准确的信息。错误的文档记录可能会导致无法预料的严重后果，超出浪费时间试图复制错误的代码示例或按照教程中的错误步骤进行操作。这是针对 acid-state 项目提出的问题的情况，acid-state 项目是为可序列化的 Haskell 数据结构提供 ACID 保证的工具。如该问题中所述，文档中的错误声明可能会导致数据丢失：“如果用户随后继续删除存档文件夹，这很容易导致永久性数据丢失，该文件夹被文档认为是安全的”。

完整性（268）。如果文档不包含从业者/用户执行其任务所需的有关系统或其模块的信息，则说明该文档不完整。

完整性占与文档内容有关的问题的 55％。我们观察到不完整的不同原因。例如，在发送到 Apache httpd 邮件列表的电子邮件中，用户抱怨缺少模糊术语的定义：“是否有“经常”的含义？的确，文档指出“ […]应该会导致频繁请求文件的性能大幅提高”，而没有明确定义“频繁请求文件”是什么。其他常见的完整性问题与缺少库组件的描述（例如，“ […]缺少有关工具栏按钮的信息”），缺少 API 使用说明（例如，“我认为我们应该添加文档以确保用户通过一棵带有重置边界的树”）和缺乏兼容性信息（例如，“明确提及是否支持 clang 4.x，5.x”）。

API 参考和代码注释是主要受完整性问题影响的文档类型。

时效性（190）。当文档与系统的其他部分不同步时，该文档已过时。时效性信息与“正确性”和“完整性”的不同之处在于，在进行更改之前，信息是正确且完整的。

时效性问题占与文档内容有关的问题的 39％。在其中 21％的情况下，似乎是系统行为与其文档中的描述不一致。差异通常是由更改文档部分或添加/删除内容所需的代码更改触发的。后一种情况通常在实施新功能时发生，例如“包括有关新的现场转换器功能的文档”。相反，在其他情况下，用户会抱怨无法使用的行为的文档（例如，“ doxygen 文档中提到的 setLeftScale 和 setRightScale 例程似乎不存在”）。

尽管大多数情况下文档不是反映代码中实现的内容，但在其他情况下，则需要更新代码以匹配文档。例如，用户质疑以非线程安全的方式实现方法，因为“根据文档，回调不是线程安全的”。

在某些情况下，需要辩论以决定代码或文档是否需要进行调整以解决不一致问题。这是一个 GitHub 问题的案例，该问题与 API 的已记录行为与实际行为之间的不一致有关：“这是代码中的错误还是文档中的错误？”。

引用过时的信息是时效性问题的另一个原因，并且可能以不同的方式影响文档。它包括在项目的 站中使用过时的信息（例如，“主页建议使用过时的命令”），代码库中过时的版权信息和版本 ，以及过时的引用（例如，系统旧版本的链接），此类别中最普遍的问题。例如，一个用户 告说“文档中链接的示例正在使用 API 的 3.x 版本，这可能会使读者感到困惑”。

一些开发人员采用了预防性解决方案以确保文档是最新的，将其添加为检查贡献待办事项列表的项目之一，甚至将 Javadoc 更新强制为接受拉取请求。

B 信息内容（How）

总共 255 个工件讨论了与文档内容的编写和组织方式有关的问题。

可用性（138）。文档的可用性是指读者可以用来有效实现其目标的程度。此类别涵盖影响用户使用文档的体验的问题。

问题的一半（50％）与信息的可发现性有关，即，当所需的信息可用但用户无法找到时，例如，“我找不到描述或实施说明”或“我找不到”似乎在任何地方都可以找到 API 文档。您能否将其托管在某个地方或将我指向那里”。开发人员通常通过向用户提供所需文档的指针来处理这些问题。在某些情况下，他们可以通过在项目 站中实施搜索功能或添加更多文档内链接来进一步改善用户体验。

信息组织（18％），即信息的直观组织方式，是该类别中第二常见的问题。将文档放置在标准位置是一种有效的做法，可以帮助用户查找它，例如，“将合并的文档编译到’docs /’文件夹中，因为正如您已经说过的那样，此位置更显眼并且更容易找到”。此外，还可以利用文档内链接简化导航，准备模板（例如，“我已经设置了可以用作新页面起点的页面模板”），并添加了“目录”以简化导航。流行的解决方案，以确保良好的信息组织。

格式不佳或不一致是另一个常见问题，尽管并不是使用文档的真正障碍（例如，“应改进标题样式以更好地分隔 H1，H2”）。通常，用户只会在出现其他类型的可用性问题时抱怨格式化（例如，“我在 revapi.org 上找不到我想要的东西，链接结构是违反直觉的，有些链接被某种程度上隐藏了”）。我们还观察到文档内一致性问题（例如，“侧边栏和文章之间的标题不一致”）和与内容组织不当有关的问题（例如，“ modules.html 上模块的顺序相当随意”）。

可用性（即文档是否可访问）也是分析工件中的问题。例如，响应正在寻找插件文档的用户，开发人员回答“很遗憾，目前还没有迁移所有插件的所有文档。目前正在进行中。”在用户正在寻找终止项目的文档的另一种情况下，建议使用 Web 存档服务（例如 Wayback Machine）。

可维护性（21）。此类涉及与文档维护相关的问题，例如，对其进行更改或更正有多么容易。就像在源代码中一样，重复的内容给文档维护人员带来了麻烦，大多数情况下可以通过使用链接和引用替换克隆来解决。但是，我们注意到文档框架通常很难避免重复。例如，由于 Jazzy（一种用于 Swift 和 Objective-C 的文档工具）的文档格式要求，当开发人员 告时，用户必须为 Xcode Quick Help（用于显示方法注释的 IDE 功能）创建不需要的副本。该文档令人生厌，但这仍然是唯一满足“快速帮助”的要求。在另一种情况下，由于 GitHub 页面与 Java 文档工具 AsciidoctorJ 之间的格式不匹配，因此文档内容保留在两个位置：“这两个位置的原因是 GitHub 无法解析包含文件”。

另一个值得注意的问题是存在多余的文件，这些文件可能会引起混乱。Apache httpd 项目的开发人员建议这样做：“摆脱这些无内容的文件，这样它们就不会混淆仍然需要记录的内容的问题”。

可读性（107）。可读性是文档易于阅读的程度。与缺乏明确性有关的问题占这些问题的一半以上（55％）。Apache stdcxx 项目的用户抱怨说：“我们能够使用用户指南中的信息来解决问题，但是文档对于确切地设置此方法颇为混乱”。摘要，太技术性和太冗长/嘈杂的信息是导致可读性差的主要原因。开发人员通过重写文档中不清楚的部分来应对这些问题，例如，“此拉取请求旨在更好地解释这两个选项之间的差异”或“我不知道这是否是最好的措辞，但我发现此行为令人困惑并且在文档中没有明确解释。希望这可以澄清一些事情。

可读性问题的第二个最常见原因是简单的错字。始终欢迎修复此类错误：“语言更正也将是值得赞赏的贡献”，尤其是当它们影响用户文档时：“ […]我们不必像对待用户可见文档那样严格。” 。

有用性（20）。如果文档对读者具有实际用途，则该文档是有用的，即，读者可以在文档的帮助下成功实现其目标。根据读者的目标，有用性可能会受到多种因素的影响。例如，在响应文档更新时，项目的所有者建议：“使这个示例更现实一点会很好”。在这种情况下，代码示例既不会过时也不会出错，但是需要进行改进才能更加有用。

许多维护者通过询问用户对文档的反馈来解决有用性。在一种情况下，开发人员通过两个步骤收集了用户反馈以改进文档 站：首先，他们在重构文档之前进行了调查；然后，他们收集了反馈以确保所做的更改能够满足用户的需求：锁定文档以了解我们应该关注的重点。现在，我们进行了是/否样式调查，以确保在改进文档时能够满足用户需求。”

讨论与启示。除了信息内容（即，文档中包含的内容）之外，信息的使用方式（即，如何有效利用其内容）还严重影响文档的质量。正如我们的分析所揭示的，所讨论问题的大部分与文档的可用性有关，这源于不良的信息组织和可查找性问题（如果找不到现有文档，则从概念上讲它不存在）。

开发人员可以通过以下方式预防/解决这些问题：（i）在项目的 站上提供搜索引擎以提高内容的可查找性； （ii）采用一致的文档格式，例如确保内部文档链接和目录存在的模板，或者采用与现有文档质量相同的样式（例如，参见 https：// docs 上的 MongoDB 文档） .mongodb.com）; （iii）在特定位置归档其项目的旧版本，废弃版本的文档，以使无法更新到较新版本的用户可以使用它们。我们还支持某些开发人员采用的调查用户的想法，以调查其文档需求。

在这种情况下，研究人员可以通过两个方向为提高文档质量做出贡献。首先，以与实施代码克隆检测技术相同的方式，检测文档克隆并自动删除（重构）它们的方法可以帮助开发人员减少文档中的冗余。其次，类似于代码可读性度量标准，为文档量身定制的可读性度量标准可以帮助开发人员发现和修复可读性问题。尽管人们可能认为软件文档仅由文本组成，因此可以使用文本的标准可读性度量标准（例如 FleschKincaid 可读性公式），但是软件文档通常是文本和使用特定领域术语的代码的组合。此外，尽管部分问题是将文档归类为高度/不良可读性，但更困难的挑战是向开发人员指示导致可读性问题的文档的确切部分。因此，创建“文档短绒”是未来研究的有趣途径。

此外，调查用户在寻找文档时的行为的研究有助于定义组织和文档呈现的更好做法。

C 工具相关问题

在本节中，我们讨论与 134 个工件中发现的文档工具（例如 Javadoc）相关的四种类型的问题。

错误/问题（17）。此类别指的是文档工具提出的问题（例如，错误，故障），这些问题不是由不正确的使用或配置引起的。

软件系统中的错误非常普遍，文档工具也不例外。

当用户不确定自己是否因使用错误或工具错误而遇到问题时，经常会在 SO 上提问。这些故事通常以问题跟踪器结尾。在一种情况下，当用户无法通过 Doxygen 解析 markdown 文件时，在 SO 上问了一个问题，说“通过此定义，这应该是错误的，还是我做错了？”。她得到了迅速的回应：“这似乎是您使用的 Markdown 解析器中的错误。你可能会考虑将其 告给该项目的开发人员”。

在另一种情况下，用户注意到 Hasdell 开发的工具集 stack haddock 不会为可执行文件或测试组件的依赖关系生成文档，而只会为库组件生成文档。尽管该问题仍未解决，并且看起来像是功能请求，但开发人员将其标记为“应该”，这意味着需要更改当前行为。

支持/期望（34）。此类别涵盖了文档工具无法满足的开发人员需求。

用户通常希望流行的工具可以在多种上下文/语言中使用，例如“是否有 GhostDoc for C ++之类的东西”或“是否有为 Ruby 提供这些 Doxygen 风格功能的工具？”。

多次要求使用现有工具的新功能，例如在用户需要从 Android Studio 快速访问 Android 文档的情况下。

自动化也经常被讨论。一个典型的例子是文档的自动部署，这是在开发人员建议为特定分支机构自动发布最新文档之后在项目中实施的。

需要帮助（90）。此类别涵盖由工具使用或配置不当而不是错误引起的问题。

在所有分析的资料中都讨论了来自文档工具的警告和错误消息。这些警告/错误的示例与使用错误的 Python 版本，文档构建配置中的错误路径，Javadoc 注释格式中的不一致以及 Javadoc 代码注释为空有关。提供工具使用示例是最普遍的解决方案。

与文档工具有关的“如何”问题，例如“如何使 Sphinx 识别类型注释？”，占该类别中观察到的问题的 83％。此类问题通常是在 SO 中提出的（79％）。格式化是主要的子问题。在一种情况下，phpDocumentor 生成的文件格式错误：“运行 phpDocumentor 时，生成的文件/文件夹看起来非常奇怪”。此问题自 2015 年 11 月起开放。

工具迁移（4）。此类别指的是与迁移相关的问题，无论是更新的工具版本还是其他工具。

在我们分析的四分之二的讨论中，观察到了迁移到同一工具的较新版本后的错误。在一种情况下，用户使用较新版本的 Javadoc 会遇到许多错误：“ javadoc 在编译工具时遇到了麻烦，我不知道为什么。自从我迁移到 Java 8 以来，它才发生过。Java7 从来没有见过这个问题。

在另一种情况下，开发人员注意到，在迁移到较新的 Sphinx 版本后，导航栏从文档中消失了。答案指出，这是默认主题的更改，但可以将其设置为以前的行为。

讨论与启示。我们确定的大多数与工具相关的问题都可以概括为用户在使用任何类型的工具时遇到的问题，而不仅仅是与文档相关的问题。这一类别中“如何”提问的盛行加强了我们对文档完整性和可查找性的发现。确实，这些问题很可能是文档工具中缺少（或很难找到）文档的结果。因此，这里对研究人员和从业人员的提炼同样适用。

我们确定了讨论功能请求或工具期望的许多工件，这些工件传达了一条信息，供从业人员注意共同的需求，例如对 IDE 集成的支持，一起处理多个文档以及自动生成文档/注释。

此外，研究人员可以开发方法来帮助用户了解他们遇到的问题是由于工具误用还是由工具的众所周知的错误引起的。例如，可以通过捕获错误的特征（例如，生成的堆栈跟踪（如果可用））来自动搜索项目的问题跟踪器和/或 SO，以进行相关讨论。

D 处理相关问题

在 81 个工件中讨论了文档处理问题

国际化（20）。此类别涵盖与翻译过程有关的问题，例如，语言翻译丢失/错误，需要检查翻译的文档以及由于字符编码而导致的渲染问题。

缺少翻译文档是一个经常出现的问题（例如，“是否开始进行丹麦语翻译？”），尤其是在没有英文文档的情况下，这对一些用户来说是一个使用障碍。这是一个主要用中文记录的项目的情况。在创建以英语为英语版本的文档的拉取请求中，主要开发人员因缺乏翻译而道歉：“大多数用户是中国人，包括我在内。我们的英语不好，很抱歉”，用户回答“我可以使用 Google 翻译，但是我在理解框架上付出的努力越多，我使用它的可能性就越小”。

许多项目都受益于将翻译进行众包，从而使外部用户可以做出贡献。为此，在代码共享平台上没有文档的项目讨论了是否移动文档以获取更多贡献：“如果我们不应该将文档推到 GitHub 上以减轻贡献，那就太好了。

缺少有关如何提供翻译的指南也是一个普遍关注的问题，主要是通过在页面上提供说明来解决，例如“我们需要一个 页来描述如何翻译 apache 文档的基础知识”。

字符编码是文档翻译上下文中另一个典型的问题根源，因为开发人员经常对选择正确的编码感到困惑。例如，在邮件列表讨论中，一个简单的问题“ .fr 文件应使用哪种编码？”，建议使用几种编码，因为考虑了诸如文件大小或客户端更好地支持的编码等因素。

可追溯性（5）。此类别涉及与跟踪文档更改的能力有关的问题，即确定更改的位置，时间，人员和原因的原因。

由文档引起的开发问题（8）。此类别涵盖由文档引起的问题，即文档对开发过程的有害影响。

为文档贡献（50）。此类别涵盖（内部或外部）文档贡献者在 告/修复错误或编写新文档时遇到的问题。它还包括开发人员对支持外部贡献者的关注。

另一个常见问题与缺乏对编写代码注释或文档的最佳实践的知识有关，例如，“如何在 JSDoc 返回类型中对此进行记录”。在另一个示例中，启动文档页面的用户通过添加“我刚刚开始某种用户指南类型的文档，欢迎发送反馈”来发送电子邮件以获取有关文档草稿版本的反馈。

Doc 生成器配置（4）。此类别涵盖与文档生成器相关的问题，这些问题通常在项目的构建过程中找到。

在 Apache SystemML 邮件列表的一个线程中观察到一个重要问题，在该线程中，由于项目的构建配置忽略了文档工具的警告，开发人员抱怨 API 注释不完整和过时。为了提高文档质量，开发人员建议将这些问题标记为阻止程序，以期在下一发行版中对其进行修复。在另一个项目中，开发人员决定将文档问题警告视为错误，从而使构建失败：“因此，现在修复警告后，也许我们可以将其更改为错误，因此当有人犯错时，它将导致构建失败”。

讨论与启示。与文档编制过程有关的许多问题都与外部贡献者可以帮助编写，更新和翻译文档的方式有关。我们的发现可以提炼为开发人员的指南，以简化文档编制过程，从而可以提高文档质量并令贡献者满意。

首先，开发人员必须向贡献者提供清晰的指导原则（最好附带文档模板），这些指导原则认真解释文档中预期涵盖的内容，应如何编写不同类型的文档（例如，代码注释）以及进行贡献的过程是。其次，开发人员必须考虑使用广泛使用的代码共享平台（例如 GitHub）来托管文档，在那里吸引来自世界各地的外部贡献者的可能性非常高，这可能有助于完成诸如翻译之类的耗时任务文档。第三，开发人员必须采用促进良好文档规范的机制，例如当通过程序分析发现文档问题时使构建失败（例如，已实现了一种新方法，但 Javadoc 中未记录其参数之一）。

开发人员的另一项收获是需要为其软件项目提供英文文档，这将增加其采用率（并可能会增加其贡献）。

相反，研究人员可以优化这些文档编制流程，并回答一些基本的研究问题，例如什么构成了良好的贡献者指南（例如，通过对软件开发人员进行调查）。最后，显然需要在自动软件文档领域取得进步。例如，当前在持续集成中使用的静态分析工具会对文档进行简单的检查（例如，识别缺失的注释），而能够在构建时检测到更复杂的文档气味的方法的开发值得研究。

4. 结论

从本质上讲，我们的研究从经验上证实并补充了先前的研究发现（和常识）：开发人员（和用户）更喜欢正确，完整，最新，可用，可维护，可读和有用的文档。

鉴于好的文档具有不可否认的价值，问题是为什么它如此并且在软件开发中仍然不受欢迎。我们认为，一方面，通过我们的研究揭示的问题证实了实现像罗比拉德等人提出的那样的愿景的必要性：系统应具有自动记录自身的能力。另一方面，这要求研究人员和从业人员接受这样的基本观念，即文档不仅仅是任何软件系统的附加组件，而是系统本身的一部分。

致谢