The DOI matches its Crossref record.
How API Documentation Fails
Abstract
Formal documentation can be a crucial resource for learning to how to use an API. However, producing high-quality documentation can be nontrivial. Researchers investigated how 10 common documentation problems manifested themselves in practice. The results are based on two surveys of a total of 323 professional software developers and analysis of 179 API documentation units. The three severest problems were ambiguity, incompleteness, and incorrectness of content. The respondents often mentioned six of the 10 problems as "blockers"' that forced them to use another API.
Overview
The claims and statistics of this paper haven’t been checked yet.
Free: it reads the open-access text and checks the first 5 claims that cite a source we can check. Create a free account to check every claim.
Integrity signals
Registry
Cites
Statistics
Verification
Claims the paper makes
The claims and statistics of this paper haven’t been checked yet.
Free: it reads the open-access text and checks the first 5 claims that cite a source we can check. Create a free account to check every claim.
Self-check
Percentages, sums and reported differences re-computed from the paper’s own numbers.
The self-check needs the paper’s full text.
Citations
Cites
No references could be resolved yet.
Research works printed but not linked: 5
- 10.1109/MS.2003.1241364 · DOI · Paper page
- 10.1109/ICSM.2012.6405249 · DOI · Paper page
- 10.1145/2393596.2393648 · DOI
- 10.1145/1882291.1882312 · DOI · Paper page
- 10.1007/s10664-010-9150-8 · DOI · Paper page
Cited by
The walkthrough method: An approach to the study of apps
Light, B., Burgess, J., & Duguay, S. (2018) · New Media & Society · doi:10.1177/1461444816675438 · Cited by 1,047
Using an LLM to Help With Code Understanding
Nam, D., Macvean, A., Hellendoorn, V., Vasilescu, B., & Myers, B. (2024) · Proceedings of the IEEE/ACM 46th International Conference on Software Engineering · doi:10.1145/3597503.3639187 · Cited by 487
“Researchers cataloged problems developers face when using documentation [9, 60, 61] and identified types of knowledge developers report to be critical [46, 60, 61, 70], which were taken into account when we designed GILT for our study.”
BackgroundSoftware Documentation Issues Unveiled
Aghajani, E., Nagy, C., Vega-Marquez, O. L., Linares-Vasquez, M., Moreno, L., Bavota, G., & Lanza, M. (2019) · 2019 IEEE/ACM 41st International Conference on Software Engineering (ICSE) · doi:10.1109/icse.2019.00122 · Cited by 195
Automatic Code Documentation Generation Using GPT-3
Khan, J. Y., & Uddin, G. (2022) · Proceedings of the 37th IEEE/ACM International Conference on Automated Software Engineering · doi:10.1145/3551349.3559548 · Cited by 96
Self-citationApplication Programming Interface Documentation: What Do Software Developers Want?
Meng, M., Steinhardt, S., & Schubert, A. (2018) · Journal of Technical Writing and Communication · doi:10.1177/0047281617721853 · Cited by 78
Experiences with Improving the Transparency of AI Models and Services
Hind, M., Houde, S., Martino, J., Mojsilovic, A., Piorkowski, D., Richards, J., & Varshney, K. R. (2020) · Extended Abstracts of the 2020 CHI Conference on Human Factors in Computing Systems · doi:10.1145/3334480.3383051 · Cited by 44
“Exacerbating these problems is the fact that documentation tends to be costly to create and maintain, and is often left as a low-priority item during software development (Uddin and Robillard 2015).”
BackgroundTurnover-induced knowledge loss in practice
Robillard, M. P. (2021) · Proceedings of the 29th ACM Joint Meeting on European Software Engineering Conference and Symposium on the Foundations of Software Engineering · doi:10.1145/3468264.3473923 · Cited by 29
“Issues with documentation have also been reported extensively in the software engineering literature (e.g., [1, 24, 51]).”
BackgroundSelf-citationUnderstanding How Programmers Can Use Annotations on Documentation
Horvath, A., Liu, M. X., Hendriksen, R., Shannon, C., Paterson, E., Jawad, K., Macvean, A., & Myers, B. A. (2022) · CHI Conference on Human Factors in Computing Systems · doi:10.1145/3491102.3502095 · Cited by 26
A Theory of Robust API Knowledge
Thayer, K., Chasins, S. E., & Ko, A. J. (2021) · ACM Transactions on Computing Education · doi:10.1145/3444945 · Cited by 25
A Survey on Online Learning Preferences for Computer Science and Programming
Escobar-Avila, J., Venuti, D., Di Penta, M., & Haiduc, S. (2019) · 2019 IEEE/ACM 41st International Conference on Software Engineering: Software Engineering Education and Training (ICSE-SEET) · doi:10.1109/icse-seet.2019.00026 · Cited by 24
Detecting outdated code element references in software repository documentation
Tan, W. S., Wagner, M., & Treude, C. (2024) · Empirical Software Engineering · doi:10.1007/s10664-023-10397-6 · Cited by 13
Automatic production of end user documentation for DSLs
Le Moulec, G., Blouin, A., Gouranton, V., & Arnaldi, B. (2018) · Computer Languages, Systems & Structures · doi:10.1016/j.cl.2018.07.006 · Cited by 3
Metadata
- Authors
- Uddin, G., & Robillard, M. P.
- Venue
- IEEE Software
- Published
- 2015-07
- Volume
- 32
- Issue
- 4
- Pages
- 68-75
- ISSN
- 0740-7459 (ISSN-L)
- 1937-4194
- OpenAlex
- W1884204318
- Cited by
- 158
- References
- 0
- FWCI
- 28.83
- Type
- journal article
- Language
- en
- Open access
- closed
About these checks
Registry, retraction, Cites and statistics results are computed, not judged, with one exception: a printed reference that no index lists is read once by a model before it counts as a citation error. Claims are extracted by a model and kept only when their quote appears verbatim in the text; each cited source is then checked, with a model’s help, for whether it says what the claim relies on. Those verdicts can be wrong — read the claim’s quote and the cited source before relying on one.
Statistics and arithmetic are recomputed, not judged.
Confidence bands are shown only for fields calibrated on our annotated test set. None is calibrated yet, so no band is shown.
What counts as a claim ›How we measure confidence ›How we check this ›
Are you an author, or do you see a problem with this page? Request a review
Data sources
Bibliographic data: Semantic Scholar, OpenAlex, Crossref.
Contains information from the Semantic Scholar Academic Graph Datasets, made available under the ODC Attribution License (ODC-BY 1.0).
Semantic Scholar’s data is described in: Kinney, R., et al. (2023). The Semantic Scholar Open Data Platform. arXiv:2301.10140.