What should I document? A preliminary systematic mapping study into API documentation knowledge
Version 3 2024-06-18, 17:55Version 3 2024-06-18, 17:55
Version 2 2024-06-04, 09:52Version 2 2024-06-04, 09:52
Version 1 2019-11-18, 14:21Version 1 2019-11-18, 14:21
conference contribution
posted on 2024-06-18, 17:55 authored by Alex CummaudoAlex Cummaudo, Rajesh VasaRajesh Vasa, J Grundy© 2019 IEEE. Background: Good API documentation facilitates the development process, improving productivity and quality. While the topic of API documentation quality has been of interest for the last two decades, there have been few studies to map the specific constructs needed to create a good document. In effect, we still need a structured taxonomy that captures such knowledge systematically.Aims: This study reports emerging results of a systematic mapping study. We capture key conclusions from previous studies that assess API documentation quality, and synthesise the results into a single framework.Method: By conducting a systematic review of 21 key works, we have developed a five dimensional taxonomy based on 34 categorised weighted recommendations.Results: All studies utilise field study techniques to arrive at their recommendations, with seven studies employing some form of interview and questionnaire, and four conducting documentation analysis. The taxonomy we synthesise reinforces that usage description details (code snippets, tutorials, and reference documents) are generally highly weighted as helpful in API documentation, in addition to design rationale and presentation.Conclusions: We propose extensions to this study aligned to developer utility for each of the taxonomy's categories.
History
Volume
2019-SeptemerPagination
1-6Location
Porto de Galinhas, Recife, BrazilPublisher DOI
Start date
2019-09-19End date
2019-09-20ISSN
1949-3770eISSN
1949-3789ISBN-13
9781728129686Language
engPublication classification
E1 Full written paper - refereedTitle of proceedings
ESEM 2019 : Proceedings of the ACM/IEEE International Symposium on Empirical Software Engineering and Measurement (ESEM)Event
ACM/IEEE International Symposium on Empirical Software Engineering and Measurement (2019 : Porto de Galinhas, Recife, Brazil)Publisher
IEEEPlace of publication
Piscataway, N.J.Series
International Symposium on Empirical Software Engineering and MeasurementUsage metrics
Categories
No categories selectedKeywords
Licence
Exports
RefWorksRefWorks
BibTeXBibTeX
Ref. managerRef. manager
EndnoteEndnote
DataCiteDataCite
NLMNLM
DCDC