What should i document? a preliminary systematic mapping study into API documentation knowledge

Alex Cummaudo, Rajesh Vasa, John Grundy

Research output: Chapter in Book/Report/Conference proceedingConference PaperResearchpeer-review

Abstract

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.

Original languageEnglish
Title of host publicationProceedings - 13th ACM/IEEE International Symposium on Empirical Software Engineering and Measurement, ESEM 2019
EditorsHakan Erdogmus, Barbara Russo
Place of PublicationPiscataway NJ USA
PublisherIEEE, Institute of Electrical and Electronics Engineers
Pages392-397
Number of pages6
ISBN (Electronic)9781728129686
ISBN (Print)9781728129693
DOIs
Publication statusPublished - 2019
EventInternational Symposium on Empirical Software Engineering and Measurement 2019 - Porto de Galinhas, Pernambuco, Brazil
Duration: 19 Sep 201920 Sep 2019
Conference number: 13th
http://eseiw2019.com/esem/

Conference

ConferenceInternational Symposium on Empirical Software Engineering and Measurement 2019
Abbreviated titleESEM 2019
CountryBrazil
CityPorto de Galinhas, Pernambuco
Period19/09/1920/09/19
Internet address

Keywords

  • API
  • DevX
  • documentation
  • systematic mapping study
  • taxonomy

Cite this

Cummaudo, A., Vasa, R., & Grundy, J. (2019). What should i document? a preliminary systematic mapping study into API documentation knowledge. In H. Erdogmus, & B. Russo (Eds.), Proceedings - 13th ACM/IEEE International Symposium on Empirical Software Engineering and Measurement, ESEM 2019 (pp. 392-397). [8870148] Piscataway NJ USA: IEEE, Institute of Electrical and Electronics Engineers. https://doi.org/10.1109/ESEM.2019.8870148
Cummaudo, Alex ; Vasa, Rajesh ; Grundy, John. / What should i document? a preliminary systematic mapping study into API documentation knowledge. Proceedings - 13th ACM/IEEE International Symposium on Empirical Software Engineering and Measurement, ESEM 2019. editor / Hakan Erdogmus ; Barbara Russo. Piscataway NJ USA : IEEE, Institute of Electrical and Electronics Engineers, 2019. pp. 392-397
@inproceedings{2cc4306c8e8a477fb52d991ad2a866b1,
title = "What should i document? a preliminary systematic mapping study into API documentation knowledge",
abstract = "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.",
keywords = "API, DevX, documentation, systematic mapping study, taxonomy",
author = "Alex Cummaudo and Rajesh Vasa and John Grundy",
year = "2019",
doi = "10.1109/ESEM.2019.8870148",
language = "English",
isbn = "9781728129693",
pages = "392--397",
editor = "Erdogmus, {Hakan } and Russo, {Barbara }",
booktitle = "Proceedings - 13th ACM/IEEE International Symposium on Empirical Software Engineering and Measurement, ESEM 2019",
publisher = "IEEE, Institute of Electrical and Electronics Engineers",
address = "United States of America",

}

Cummaudo, A, Vasa, R & Grundy, J 2019, What should i document? a preliminary systematic mapping study into API documentation knowledge. in H Erdogmus & B Russo (eds), Proceedings - 13th ACM/IEEE International Symposium on Empirical Software Engineering and Measurement, ESEM 2019., 8870148, IEEE, Institute of Electrical and Electronics Engineers, Piscataway NJ USA, pp. 392-397, International Symposium on Empirical Software Engineering and Measurement 2019, Porto de Galinhas, Pernambuco, Brazil, 19/09/19. https://doi.org/10.1109/ESEM.2019.8870148

What should i document? a preliminary systematic mapping study into API documentation knowledge. / Cummaudo, Alex; Vasa, Rajesh; Grundy, John.

Proceedings - 13th ACM/IEEE International Symposium on Empirical Software Engineering and Measurement, ESEM 2019. ed. / Hakan Erdogmus; Barbara Russo. Piscataway NJ USA : IEEE, Institute of Electrical and Electronics Engineers, 2019. p. 392-397 8870148.

Research output: Chapter in Book/Report/Conference proceedingConference PaperResearchpeer-review

TY - GEN

T1 - What should i document? a preliminary systematic mapping study into API documentation knowledge

AU - Cummaudo, Alex

AU - Vasa, Rajesh

AU - Grundy, John

PY - 2019

Y1 - 2019

N2 - 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.

AB - 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.

KW - API

KW - DevX

KW - documentation

KW - systematic mapping study

KW - taxonomy

UR - http://www.scopus.com/inward/record.url?scp=85074298992&partnerID=8YFLogxK

U2 - 10.1109/ESEM.2019.8870148

DO - 10.1109/ESEM.2019.8870148

M3 - Conference Paper

SN - 9781728129693

SP - 392

EP - 397

BT - Proceedings - 13th ACM/IEEE International Symposium on Empirical Software Engineering and Measurement, ESEM 2019

A2 - Erdogmus, Hakan

A2 - Russo, Barbara

PB - IEEE, Institute of Electrical and Electronics Engineers

CY - Piscataway NJ USA

ER -

Cummaudo A, Vasa R, Grundy J. What should i document? a preliminary systematic mapping study into API documentation knowledge. In Erdogmus H, Russo B, editors, Proceedings - 13th ACM/IEEE International Symposium on Empirical Software Engineering and Measurement, ESEM 2019. Piscataway NJ USA: IEEE, Institute of Electrical and Electronics Engineers. 2019. p. 392-397. 8870148 https://doi.org/10.1109/ESEM.2019.8870148