Documentation for programming languages and their APIs takes many forms, such as reference documentation, blog posts or other textual and visual media. Prior research has suggested that developers switch between reference and tutorial-like documentation while learning a new API. Documentation creation and maintenance is also an effort-intensive process that requires its creators to carefully inspect and organize information, while ensuring consistency across different sources. This article reports on the relationship between information in tutorials and in API reference documentation of three libraries on the topics: regular expressions, unified resource location and Input/Output in the two programming languages, Java and Python. Our investigation reveals that about half of the sentences in the tutorials studied describe API Information , i.e. syntax, behaviour, usage and performance of the API, that could be found in the reference documentation. The remaining are tutorial specific use-cases and examples. We also elicited and analyzed six types of correspondences between sentences in tutorials and reference documentation, ranging from identical to implied . Based on our findings, we propose a general information reuse pattern as a structured abstraction to represent the systematic integration of information from the reference documentation into a tutorial. We report on the distribution of 38 instances of this pattern, and on the impact of applying the pattern automatically on the existing tutorials. This work lays a foundation for understanding the nature of information correspondence across different documentation types to inform and assist documentation generation and maintenance.

中文翻译：

---

API 文档类型之间的信息对应关系

编程语言及其 API 的文档有多种形式，例如参考文档、博客文章或其他文本和视觉媒体。先前的研究表明，开发人员在学习新 API 时，应在参考文档和类似教程的文档之间切换。文档创建和维护也是一个费力的过程，需要其创建者仔细检查和组织信息，同时确保不同来源之间的一致性。本文报告了教程和 API 参考文档中关于正则表达式、统一资源位置和两种编程语言 Java 和 Python 的输入/输出主题的三个库的信息之间的关系。我们的调查显示，所研究的教程中约有一半的句子描述了 API 信息，即 API 的语法、行为、用法和性能，可在参考文档中找到。其余的是教程特定的用例和示例。我们还引出并分析了教程和参考文档中句子之间的六种类型的对应关系，从相同到隐含。根据我们的发现，我们提出了一种通用信息重用模式作为结构化抽象，以表示将参考文档中的信息系统集成到教程中。我们报告了此模式的 38 个实例的分布，以及自动应用该模式对现有教程的影响。这项工作为理解不同文档类型的信息对应的性质奠定了基础，以告知和协助文档生成和维护。API 的行为、用法和性能，可在参考文档中找到。其余的是教程特定的用例和示例。我们还引出并分析了教程和参考文档中句子之间的六种类型的对应关系，从相同到隐含。根据我们的发现，我们提出了一种通用信息重用模式作为结构化抽象，以表示将参考文档中的信息系统集成到教程中。我们报告了此模式的 38 个实例的分布，以及自动应用该模式对现有教程的影响。这项工作为理解不同文档类型的信息对应的性质奠定了基础，以告知和协助文档生成和维护。API 的行为、用法和性能，可在参考文档中找到。其余的是教程特定的用例和示例。我们还引出并分析了教程和参考文档中句子之间的六种类型的对应关系，从相同到隐含。根据我们的发现，我们提出了一种通用信息重用模式作为结构化抽象，以表示将参考文档中的信息系统集成到教程中。我们报告了此模式的 38 个实例的分布，以及自动应用该模式对现有教程的影响。这项工作为理解不同文档类型的信息对应的性质奠定了基础，以告知和协助文档生成和维护。API 的使用和性能，可以在参考文档中找到。其余的是教程特定的用例和示例。我们还引出并分析了教程和参考文档中句子之间的六种类型的对应关系，从相同到隐含。根据我们的发现，我们提出了一种通用信息重用模式作为结构化抽象，以表示将参考文档中的信息系统集成到教程中。我们报告了此模式的 38 个实例的分布，以及自动应用该模式对现有教程的影响。这项工作为理解不同文档类型的信息对应的性质奠定了基础，以告知和协助文档生成和维护。API 的使用和性能，可以在参考文档中找到。其余的是教程特定的用例和示例。我们还引出并分析了教程和参考文档中句子之间的六种类型的对应关系，从相同到隐含。根据我们的发现，我们提出了一种通用信息重用模式作为结构化抽象，以表示将参考文档中的信息系统集成到教程中。我们报告了此模式的 38 个实例的分布，以及自动应用该模式对现有教程的影响。这项工作为理解不同文档类型的信息对应的性质奠定了基础，以告知和协助文档生成和维护。