Application Programming Interface Documentation: What Do Software Developers Want?
The DOI matches its Crossref record; 37 of the 37 references it cites were found in a registry or an index.
Abstract
The success of an application programming interface (API) crucially depends on how well its documentation meets the information needs of software developers. Previous research suggests that these information needs have not been sufficiently understood. This article presents the results of a series of semistructured interviews and a follow-up questionnaire conducted to explore the learning goals and learning strategies of software developers, the information resources they turn to and the quality criteria they apply to API documentation. Our results show that developers initially try to form a global understanding regarding the overall purpose and main features of an API, but then adopt either a concepts-oriented or a code-oriented learning strategy that API documentation both needs to address. Our results also show that general quality criteria such as completeness and clarity are relevant to API documentation as well. Developing and maintaining API documentation therefore need to involve the expertise of communication professionals.
Overview
Integrity signals
Registry
Cites
Statistics
Verification
Claims the paper makes
Citations
Cites
R: A Language and Environment for Statistical Computing
R Core Team (2025) · doi:10.32614/r.manuals · Cited by 352,181
Qualitative Content Analysis: Theoretical Background and Procedures
Mayring, P. (2015) · Advances in Mathematics Education · doi:10.1007/978-94-017-9181-6_13 · Cited by 2,263
Self-Directed Learning, A Guide for Learners and Teachers
McNally, J. M. (1976) · The Journal of Continuing Education in Nursing · doi:10.3928/0022-0124-19760501-17 · Cited by 2,234
Qualitative Text Analysis: A Guide to Methods, Practice & Using Software
Kuckartz, U. (2014) · doi:10.4135/9781446288719 · Cited by 1,411
(2009) · doi:10.1057/9780230244276 · Cited by 672
Information Needs in Collocated Software Development Teams
Ko, A. J., DeLine, R., & Venolia, G. (2007) · 29th International Conference on Software Engineering (ICSE'07) · doi:10.1109/icse.2007.45 · Cited by 499 · cited 1×
“Communication is reported to be preferred over documentation in studies focusing more broadly on software development and maintenance (Ko, DeLine, & Venolia, 2007; Maalej et al., 2014).”
Studying Software Engineers: Data Collection Techniques for Software Field Studies
Lethbridge, T. C., Sim, S. E., & Singer, J. (2005) · Empirical Software Engineering · doi:10.1007/s10664-005-1290-x · Cited by 494
How do programmers ask and answer questions on the web? (NIER track)
Treude, C., Barzilay, O., & Storey, M.-A. (2011) · Proceedings of the 33rd International Conference on Software Engineering · doi:10.1145/1985793.1985907 · Cited by 405
Schriver, K. A. (1998) · College Composition and Communication · doi:10.2307/358576 · Cited by 384
What Makes APIs Hard to Learn? Answers from Developers
Robillard, M. P. (2009) · IEEE Software · doi:10.1109/ms.2009.193 · Cited by 382
A field study of API learning obstacles
Robillard, M. P., & DeLine, R. (2011) · Empirical Software Engineering · doi:10.1007/s10664-010-9150-8 · Cited by 352
Experiences from Conducting Semi-structured Interviews in Empirical Software Engineering Research
Hove, S. E., & Anda, B. (2005) · 11th IEEE International Software Metrics Symposium (METRICS'05) · doi:10.1109/metrics.2005.24 · Cited by 345
How software engineers use documentation: the state of the practice
Lethbridge, T. C., Singer, J., & Forward, A. (2003) · IEEE Software · doi:10.1109/ms.2003.1241364 · Cited by 343
Myers, B. A., & Stylos, J. (2016) · Communications of the ACM · doi:10.1145/2896587 · Cited by 269
Mica: A Web-Search Tool for Finding API Components and Examples
Stylos, J., & Myers, B. A. (2006) · Visual Languages and Human-Centric Computing (VL/HCC'06) · doi:10.1109/vlhcc.2006.32 · Cited by 224
Lannon, J. M., & Gurak, L. J. (1999) · Cited by 224
Patterns of Knowledge in API Reference Documentation
Maalej, W., & Robillard, M. P. (2013) · IEEE Transactions on Software Engineering · doi:10.1109/tse.2013.12 · Cited by 183
On the Comprehension of Program Comprehension
Maalej, W., Tiarks, R., Roehm, T., & Koschke, R. (2014) · ACM Transactions on Software Engineering and Methodology · doi:10.1145/2622669 · Cited by 180
Uddin, G., & Robillard, M. P. (2015) · IEEE Software · doi:10.1109/ms.2014.80 · Cited by 158
Technical Communication and Usability: Intertwined Strands and Mutual Influences
Redish, J. (2010) · IEEE Transactions on Professional Communication · doi:10.1109/tpc.2010.2052861 · Cited by 147
Dagenais, B., & Robillard, M. P. (2010) · Proceedings of the eighteenth ACM SIGSOFT international symposium on Foundations of software engineering · doi:10.1145/1882291.1882312 · Cited by 124
An ethnographic study of copy and paste programming practices in OOPL
Kim, M., Bergman, L., Lau, T., & Notkin, D. (2004) · Proceedings. 2004 International Symposium on Empirical Software Engineering, 2004. ISESE '04. · doi:10.1109/isese.2004.1334896 · Cited by 117
Usability Implications of Requiring Parameters in Objects' Constructors
Stylos, J., & Clarke, S. (2007) · 29th International Conference on Software Engineering (ICSE'07) · doi:10.1109/icse.2007.92 · Cited by 110
McLellan, S. G., Roesler, A., Tempest, J. T., & Spinuzzi, C. (1998) · IEEE Software · doi:10.1109/52.676963 · Cited by 110
Investigating reading techniques for object-oriented framework learning
Basili, V. R., Lanubile, F., & Shull, F. J. (2000) · IEEE Transactions on Software Engineering · doi:10.1109/32.881720 · Cited by 92
The Usability of Print and Online Video Instructions
Alexander, K. P. (2013) · Technical Communication Quarterly · doi:10.1080/10572252.2013.775628 · Cited by 85
Improving API documentation using API usage information
Stylos, J., Faulring, A., Yang, Z., & Myers, B. A. (2009) · 2009 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC) · doi:10.1109/vlhcc.2009.5295283 · Cited by 81
Obstacles in Using Frameworks and APIs: An Exploratory Study of Programmers' Newsgroup Discussions
Hou, D., & Li, L. (2011) · 2011 IEEE 19th International Conference on Program Comprehension · doi:10.1109/icpc.2011.21 · Cited by 77
Usage and usefulness of technical software documentation: An industrial case study
Garousi, G., Garousi, V., Ruhe, G., Zhi, J., Moussavi, M., & Smith, B. (2014) · Information and Software Technology · doi:10.1016/j.infsof.2014.08.003 · Cited by 73
What programmers really want: results of a needs assessment for SDK documentation
Nykaza, J., Messinger, R., Boehme, F., Norman, C. L., Mace, M., & Gordon, M. (2002) · Proceedings of the 20th annual international conference on Computer documentation · doi:10.1145/584955.584976 · Cited by 61
Revealing actual documentation usage in software maintenance through war stories
Lutters, W. G., & Seaman, C. B. (2007) · Information and Software Technology · doi:10.1016/j.infsof.2007.02.013 · Cited by 59
Preliminary Empirical Identification of Barriers Faced by Newcomers to Open Source Software Projects
Steinmacher, I., Chaves, A. P., Conte, T. U., & Gerosa, M. A. (2014) · 2014 Brazilian Symposium on Software Engineering · doi:10.1109/sbes.2014.9 · Cited by 53
The information gathering strategies of software maintainers
Seaman, C. B. (2003) · International Conference on Software Maintenance · doi:10.1109/icsm.2002.1167761 · Cited by 53
Usability in computer documentation design: conceptual and methodological considerations
Guillemette, R. A. (1989) · IEEE Transactions on Professional Communication · doi:10.1109/47.44534 · Cited by 40
Improving Documentation for eSOA APIs through User Studies
Jeong, S. Y., Xie, Y., Beaton, J., Myers, B. A., Stylos, J., Ehret, R., Karstens, J., Efeoğlu, A., & Busse, D. K. (2009) · Lecture notes in computer science · doi:10.1007/978-3-642-00427-8_6 · Cited by 35
The role of conceptual knowledge in API usability
Ko, A. J., & Riche, Y. (2011) · 2011 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC) · doi:10.1109/vlhcc.2011.6070395 · Cited by 30
App-directed learning: An exploratory study
Sillito, J., & Begel, A. (2013) · International Workshop on Cooperative and Human Aspects of Software Engineering (CHASE) · doi:10.1109/chase.2013.6614736 · Cited by 10
Research works printed but not linked: 6
- Clarke S., 2004, Dr. Dobb’s Journal, 29, S6
- Clarke, S. (2007). What is an end user software engineer? In Dagstuhl Seminar Proceedings . Schloss Dagstuhl-Leibniz-Zentrum für Informatik. Retrieved from http://drops.dagstuhl.de/opus/volltexte/2007/1080/.
- Mayring P., 2015, Qualitative Inhaltsanalyse: Grundlagen und Techniken [Qualitative content analysis: Foundations and procedures]
- Stylos, J. (2009). Making APIs more usable with improved API design, documentation and tools (Doctoral dissertation). Carnegie Mellon University. Retrieved from http://www.cs.cmu.edu/∼NatProg/papers/.
- Watson, R. B. (2015). The effect of visual design and information content on readers’ assessments of API reference topics (Doctoral dissertation). University of Washington. Retrieved from https://digital.lib.washington.edu/researchworks/.
- Zibran M., 2008, International Journal of Computer Science and Network Security, 8, 255
Cited by
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
“During the pilot studies, we observed that participants approached the tasks differently depending on their familiarity with other LLM-based tools, and styles of information processing and learning as observed in many previous studies on software documentation and debugging [4, 46, 47].”
BackgroundMethodBeyond Browsing: API-Based Web Agents
Song, Y., Xu, F. F., Zhou, S., & Neubig, G. (2025) · Findings of the Association for Computational Linguistics: ACL (Findings of ACL) · doi:10.18653/v1/2025.findings-acl.577 · Cited by 97
Ueafuea, K., Boonnag, C., Sudhawiyangkul, T., Leelaarporn, P., Gulistan, A., Chen, W., Mukhopadhyay, S. C., Wilaiprasitporn, T., & Piyayotai, S. (2020) · IEEE Sensors Journal · doi:10.1109/jsen.2020.3046259 · Cited by 82
“Developers Are Responsible”: What Ad Networks Tell Developers About Privacy
Tahaei, M., & Vaniea, K. E. (2021) · CHI Conference Extended Abstracts on Human Factors in Computing Systems (CHI EA) · doi:10.1145/3411763.3451805 · Cited by 54
Weaving seams with data: Conceptualizing City APIs as elements of infrastructures
Raetzsch, C., Pereira, G., Vestergaard, L. S., & Brynskov, M. (2019) · Big Data & Society · doi:10.1177/2053951719827619 · Cited by 49
Metadata
- Authors
- Meng, M., Steinhardt, S., & Schubert, A.
- Affiliations
- Merseburg University of Applied Sciences (DE)
- Corresponding author
- Meng, Michael
- Venue
- Journal of Technical Writing and Communication
- Publisher
- SAGE Publications
- Published
- 2017-07-26
- Volume
- 48
- Issue
- 3
- Pages
- 295-330
- ISSN
- 0047-2816 (ISSN-L)
- 1541-3780
- OpenAlex
- W2739693438
- Cited by
- 78
- References
- 37
- Citations by year
- 2026: 4 · 2025: 3 · 2024: 17 · 2023: 13 · 2022: 13 · 2021: 14 · 2020: 8 · 2019: 3 · 2018: 3
- FWCI
- 7.13
- Type
- journal article
- Language
- en
- Open access
- closed
- Licence
- journals.sagepub.com/page/policies/text-and-data-mining-license (tdm)
- Locations
- Journal of Technical Writing and Communication (publishedVersion)
- Topics
- Physical Sciences › Computer Science › Information Systems › Software Engineering Research
- Physical Sciences › Computer Science › Information Systems › Software Engineering Techniques and Practices
- Physical Sciences › Computer Science › Human-Computer Interaction › Usability and User Interface Design
- Keywords
- application programming interfaces, API documentation, software developers, information needs, learning strategies, documentation completeness, technical communication
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.