This Article 
   
 Share 
   
 Bibliographic References 
   
 Add to: 
 
Digg
Furl
Spurl
Blink
Simpy
Google
Del.icio.us
Y!MyWeb
 
 Search 
   
What Makes APIs Hard to Learn? Answers from Developers
November/December 2009 (vol. 26 no. 6)
pp. 27-34
Martin P. Robillard, McGill University
Most software projects reuse components exposed through APIs, which provide developers access to implemented functionality. APIs have grown large and diverse, which raises questions regarding their usability. This article reports on a study of the obstacles professional developers at Microsoft faced when learning how to use APIs. The study was grounded in developers' experience, collected through a survey and interviews. The resulting data showed that learning resources for APIs are critically important and shed light on three issues: the need to discover the design and rationale of the API when needed, the challenge of finding credible usage API examples at the right level of complexity, and the challenge of understanding inexplicable API behavior. The article describes each of these challenges in detail and discusses associated implications for API users and designers.

1. S.G. McLellan et al., "Building More Usable APIs," IEEE Software, May/June 1998, pp. 78–86.
2. J. Stylos, and S. Clarke, "Usability Implications of Requiring Parameters in Objects' Constructors," Proc. 29th Int'l Conf. Software Engineering (ICSE 07), IEEE CS Press, 2007, pp. 529–539.
3. K. Cwalina and B. Abrams, Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd ed., Addison-Wesley, 2009.
4. S. Clarke, "Measuring API Usability," Dr. Dobb's J. Special Windows/.NET Supplement, May 2004.
5. J. Bloch, "How to Design a Good API and Why It Matters," Companion to the 21st ACM SIGPLAN Symp. Object-Oriented Programming Systems, Languages, and Applications (OOPSLA 06), ACM Press, 2006, pp. 506–507.
6. B.A. Kitchenham and S.L. Pfleeger, "Chapter 3: Personal Opinion Surveys," Guide to Advanced Empirical Software Engineering, F. Shull, J. Singer, and D.I.K. Sj⊘berg eds., Springer, 2008, pp. 63–92.
7. J. Nykaza et al., "What Programmers Really Want: Results of a Needs Assessment for SDK Documentation," Proc. 20th ACM SIGDOC Ann. Int'l Conf. Computer Documentation, IEEE CS Press, 2002, pp. 133–141.
8. R.S. Weiss, , Learning from Strangers: The Art and Method of Qualitative Interview Studies, Free Press, 1994.
9. F. Shull, F. Lanubile, and V.R. Basili, "Investigating Reading Techniques for Object-Oriented Framework Learning," IEEE Trans. Software Eng., vol. 26, no. 11, 2000, pp. 1101–1118.

Index Terms:
API usability, software documentation, code examples, API design, empirical study
Citation:
Martin P. Robillard, "What Makes APIs Hard to Learn? Answers from Developers," IEEE Software, vol. 26, no. 6, pp. 27-34, Nov.-Dec. 2009, doi:10.1109/MS.2009.193
Usage of this product signifies your acceptance of the Terms of Use.