Information correspondence between types of documentation for APIs
- PDF / 3,555,915 Bytes
- 28 Pages / 439.642 x 666.49 pts Page_size
- 99 Downloads / 223 Views
Information correspondence between types of documentation for APIs Deeksha M. Arya1
· Jin L. C. Guo1 · Martin P. Robillard1
© Springer Science+Business Media, LLC, part of Springer Nature 2020
Abstract 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. Keywords Software documentation · Application programming interface · Qualitative analysis · Exploratory study Communicated by: Martin Monperrus Deeksha M. Arya
[email protected] Jin L. C. Guo [email protected] Martin P. Robillard [email protected] 1
McGill University, Montreal, Canada
Empirical Software Engineering
1 Introduction Complete, correct and consistent documentation for application programming interfaces (APIs) is a boon for developers to understand the functionalities of software and to master their usage. API documentation may be presented in many forms, including reference documentation and tutorials. We define reference documentation as a dictionary-style document indexed by API element and intended mostly for retrieving specific technical information. In contrast, we define a tutorial as a document intended primarily to teach its users how to use a technology, without specific constraints on the structure of the document (such as a direct mapping to the underlying API). Despite the availability of documentation, Robillard (2009) and Uddin and Robillard (2015) observed that API reference documentation la
Data Loading...
