This Article 
   
 Share 
   
 Bibliographic References 
   
 Add to: 
 
Digg
Furl
Spurl
Blink
Simpy
Google
Del.icio.us
Y!MyWeb
 
 Search 
   
Patterns of Knowledge in API Reference Documentation
Sept. 2013 (vol. 39 no. 9)
pp. 1264-1282
Walid Maalej, University of Hamburg, Germany
Martin P. Robillard, McGill University, Montréal
Reading reference documentation is an important part of programming with application programming interfaces (APIs). Reference documentation complements the API by providing information not obvious from the API syntax. To improve the quality of reference documentation and the efficiency with which the relevant information it contains can be accessed, we must first understand its content. We report on a study of the nature and organization of knowledge contained in the reference documentation of the hundreds of APIs provided as a part of two major technology platforms: Java SDK 6 and .NET 4.0. Our study involved the development of a taxonomy of knowledge types based on grounded methods and independent empirical validation. Seventeen trained coders used the taxonomy to rate a total of 5,574 randomly sampled documentation units to assess the knowledge they contain. Our results provide a comprehensive perspective on the patterns of knowledge in API documentation: observations about the types of knowledge it contains and how this knowledge is distributed throughout the documentation. The taxonomy and patterns of knowledge we present in this paper can be used to help practitioners evaluate the content of their API documentation, better organize their documentation, and limit the amount of low-value content. They also provide a vocabulary that can help structure and facilitate discussions about the content of APIs.
Index Terms:
Documentation,Taxonomy,Encoding,Reliability,Java,Software,Sociology,.NET,API documentation,software documentation,empirical study,content analysis,grounded method,data mining,pattern mining,Java
Citation:
Walid Maalej, Martin P. Robillard, "Patterns of Knowledge in API Reference Documentation," IEEE Transactions on Software Engineering, vol. 39, no. 9, pp. 1264-1282, Sept. 2013, doi:10.1109/TSE.2013.12
Usage of this product signifies your acceptance of the Terms of Use.