Patterns of Knowledge in API Reference Documentation
“Patterns of Knowledge in API Reference Documentation” is the title of the new paper by Prof. Maalej and Prof. Robillard, which has been recently accepted for publication at the renowned journal IEEE Transactions on Software Engineering.
Walid Maalej and Martin P. Robillard
Reading reference documentation is an important part of programming with 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 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 5574 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 provides a vocabulary that can help structure and facilitate discussions about the content of APIs.
*This is the authors’ version of the work. The final formal version should be accessed via IEEE DL and might slightly differ from this preprint version