![[PDF]](/pb-assets/Icons/adobe-pdf-icon-1498649896243.png){kind=icon}
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.
References
| Alexander, K. P. (2013) The usability of print and online video instructions. Technical Communication Quarterly 22(3): 237–259. Google Scholar | Crossref | |
| Bogner, A., Littig, B., Menz, W. (2009) Interviewing experts (Research Methods Series), London, England: Palgrave Macmillan. Google Scholar | Crossref | |
| Clarke, S. (2004) Measuring API usability. Dr. Dobb’s Journal 29: S6–S9. Retrieved from http://www.drdobbs.com/windows/measuring-api-usability/184405654. Google Scholar | |
| 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/. Google Scholar | |
| Dagenais, B., & Robillard, M. P. (2010). Creating and evolving developer documentation: Understanding the decisions of open source contributors. In Proceedings of the 18th ACM SIGSOFT International Symposium on Foundations of Software Engineering (pp. 127–136). New York, NY: ACM. Google Scholar | |
| Garousi, G., Garousi-Yusifoğlu, V., Ruhe, G., Zhi, J., Moussavi, M., Smith, B. (2015) Usage and usefulness of technical software documentation: An industrial case study. Information and Software Technology 57: 664–682. Google Scholar | Crossref | |
| Guillemette, R. A. (1989) Usability in computer documentation design: Conceptual and methodological considerations. IEEE Transactions on Professional Communication 32(4): 217–229. Google Scholar | Crossref | |
| Hou, D., & Li, L. (2011). Obstacles in using frameworks and APIs: An exploratory study of programmers’ newsgroup discussions. In Proceedings of 2011 IEEE 19th International Conference on Program Comprehension (pp. 91–100). Washington, DC: IEEE. Google Scholar | |
| Hove, S. E., & Anda, B. (2005). Experiences from conducting semi-structured interviews in empirical software engineering research. In Proceedings of 11th IEEE International Symposium on Software Metrics (pp. 10–23). Washington, DC: IEEE. Google Scholar | |
| Jeong, S. Y., Xie, Y., Beaton, J., Myers, B. A., Stylos, J., Ehret, R., & Busse, D. K. (2009). Improving documentation for eSOA APIs through user studies. In International Symposium on End User Development (pp. 86–105). Berlin, Germany: Springer. Google Scholar | |
| Kim, M., Bergman, L., Lau, T., & Notkin, D. (2004). An ethnographic study of copy and paste programming practices in OOPL. In Proceedings of International Symposium on Empirical Software Engineering (pp. 83–92). Washington, DC: IEEE. Google Scholar | |
| Knowles, M. S. (1975) Self-directed learning: A guide for learners and teachers, New York, NY: Cambridge Book Company. Google Scholar | |
| Ko, A. J., DeLine, R., & Venolia, G. (2007). Information needs in collocated software development teams. In Proceedings of 29th International Conference on Software Engineering (pp. 344–353). Washington, DC: IEEE. Google Scholar | |
| Ko, A. J., & Riche, Y. (2011). The role of conceptual knowledge in API usability. In Proceedings of 2011 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC) (pp. 173–176). Washington, DC: IEEE. Google Scholar | |
| Kuckartz, U. (2014) Qualitative text analysis: A guide to methods, practice and using software, Los Angeles, CA: Sage. Google Scholar | Crossref | |
| Lethbridge, T. C., Sim, S. E., Singer, J. (2005) Studying software engineers: Data collection techniques for software field studies. Empirical Software Engineering 10(3): 311–341. Google Scholar | Crossref | |
| Lethbridge, T. C., Singer, J., Forward, A. (2003) How software engineers use documentation: The state of the practice. IEEE Software 20(6): 35–39. Google Scholar | Crossref | |
| Lutters, W. G., Seaman, C. B. (2007) Revealing actual documentation usage in software maintenance through war stories. Information and Software Technology 49(6): 576–587. Google Scholar | Crossref | |
| Maalej, W., Robillard, M. P. (2013) Patterns of knowledge in API reference documentation. IEEE Transactions on Software Engineering 39(9): 1264–1282. Google Scholar | Crossref | |
| Maalej, W., Tiarks, R., Roehm, T., Koschke, R. (2014) On the comprehension of program comprehension. ACM Transactions on Software Engineering and Methodology (TOSEM) 23(4): 31. Google Scholar | Crossref | |
| Mayring, P. (2014). Qualitative content analysis: Theoretical foundation, basic procedures and software solution. Retrieved from http://nbn-resolving.de/urn:nbn:de:0168-ssoar-395173. Google Scholar | |
| Mayring, P. (2015) Qualitative Inhaltsanalyse: Grundlagen und Techniken [Qualitative content analysis: Foundations and procedures], 12th ed. Weinheim, Germany: Beltz. Google Scholar | |
| McLellan, S. G., Roesler, A. W., Tempest, J. T., Spinuzzi, C. I. (1998) Building more usable APIs. IEEE Software 15(3): 78–86. Google Scholar | Crossref | |
| Mihaly, F. (2011). Writing helpful API documentation [Blog post]. Retrieved from http://theamiableapi.com/2011/11/01/api-design-best-practice-write-helpful-documentation/. Google Scholar | |
| Myers, B. A., Stylos, J. (2016) Improving API usability. Communications of the ACM 59(6): 62–69. Google Scholar | Crossref | |
| Nykaza, J., Messinger, R., Boehme, F., Norman, C. L., Mace, M., & Gordon, M. (2002). What programmers really want: Results of a needs assessment for SDK documentation. In Proceedings of the 20th Annual International Conference on Computer Documentation (pp. 133–141). New York, NY: ACM. Google Scholar | |
| Parnin, C. (2013). API documentation–Why it sucks [Blog post]. Retrieved from http://blog.ninlabs.com/2013/03/api-documentation/. Google Scholar | |
| R Core Team (2016) R: A language and environment for statistical computing, Vienna, Austria: R Foundation for Statistical Computing. Google Scholar | |
| Redish, J. C. G. (2000) What is information design? Technical Communication 47(2): 163–166. Google Scholar | |
| Redish, J. C. G. (2010) Technical communication and usability: Intertwined strands and mutual influences. IEEE Transactions on Professional Communication 53(3): 191–201. Google Scholar | Crossref | |
| Robillard, M. P. (2009) What makes APIs hard to learn? Answers from developers. IEEE Software 26(6): 27–34. Google Scholar | Crossref | |
| Robillard, M. P., DeLine, R. (2011) A field study of API learning obstacles. Empirical Software Engineering 16(6): 703–732. Google Scholar | Crossref | |
| Schriver, K. A. (1997) Dynamics in document design, New York, NY: John Wiley & Sons, Inc. Google Scholar | |
| Seaman, C. B. (2002). The information gathering strategies of software maintainers. In Proceedings of International Conference on Software Maintenance (pp. 141–149). Washington, DC: IEEE. Google Scholar | |
| Shull, F., Lanubile, F., Basili, V. R. (2000) Investigating reading techniques for object-oriented framework learning. IEEE Transactions on Software Engineering 26(11): 1101–1118. Google Scholar | Crossref | |
| Sillito, J., & Begel, A. (2013). App-directed learning: An exploratory study. Proceedings of 6th International Workshop on Cooperative and Human Aspects of Software Engineering (pp. 81–84). Washington, DC: IEEE. Google Scholar | |
| Steinmacher, I., Chaves, A. P., Conte, T. U., & Gerosa, M. A. (2014). Preliminary empirical identification of barriers faced by newcomers to Open Source Software projects. In Brazilian Symposium on Software Engineering (pp. 51–60). Washington, DC: IEEE. Google Scholar | |
| 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/. Google Scholar | |
| Stylos, J., & Clarke, S. (2007). Usability implications of requiring parameters in objects' constructors. In Proceedings of 29th International Conference on Software Engineering (pp. 529–539). Washington, DC: IEEE. Google Scholar | |
| Stylos, J., Faulring, A., Yang, Z., & Myers, B. A. (2009). Improving API documentation using API usage information. In Proceedings of IEEE Symposium on Visual Languages and Human-Centric Computing (pp. 119–126). Washington, DC: IEEE. Google Scholar | |
| Stylos, J., & Myers, B. A. (2006). Mica: A web-search tool for finding API components and examples. In Proceedings of IEEE Symposium on Visual Languages and Human-Centric Computing (pp. 195–202). Washington, DC: IEEE. Google Scholar | |
| Treude, C., Barzilay, O., & Storey, M. A. (2011, May). How do programmers ask and answer questions on the web? Nier track. In Proceedings of 33rd International Conference on Software Engineering (pp. 804–807). Washington, DC: IEEE. Google Scholar | |
| Uddin, G., Robillard, M. P. (2015) How API documentation fails. IEEE Software 32(4): 68–75. Google Scholar | Crossref | |
| 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/. Google Scholar | |
| Zibran, M. (2008) What makes APIs difficult to use? International Journal of Computer Science and Network Security 8(4): 255–261. Google Scholar |
