Application Programming Interface Documentation: What Do Software Developers Want?

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.

[1]  Robert B. Watson,et al.  The Effect of Visual Design and Information Content on Readers’ Assessments of API Reference Topics , 2015 .

[2]  Udo Kuckartz,et al.  Qualitative Text Analysis: A Guide to Methods, Practice & Using Software , 2013 .

[3]  R Core Team,et al.  R: A language and environment for statistical computing. , 2014 .

[4]  Kara Poe Alexander.  The Usability of Print and Online Video Instructions , 2013 .

[5]  Andrew Begel,et al.  App-directed learning: An exploratory study , 2013, 2013 6th International Workshop on Cooperative and Human Aspects of Software Engineering (CHASE).

[6]  Janice Redish,et al.  Technical Communication and Usability: Intertwined Strands and Mutual Influences , 2010, IEEE Transactions on Professional Communication.

[7]  Brad A. Myers,et al.  Improving API documentation using API usage information , 2009, 2009 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC).

[8]  Martin P. Robillard,et al.  A field study of API learning obstacles , 2011, Empirical Software Engineering.

[9]  Richard Baskerville,et al.  Information design , 2011, Eur. J. Inf. Syst..

[10]  Martin P. Robillard,et al.  Patterns of Knowledge in API Reference Documentation , 2013, IEEE Transactions on Software Engineering.

[11]  Bente Anda,et al.  Experiences from conducting semi-structured interviews in empirical software engineering research , 2005, 11th IEEE International Software Metrics Symposium (METRICS'05).

[12]  Mauro Overend,et al.  Interviewing the Experts , 2014 .

[13]  Yann Riche,et al.  The role of conceptual knowledge in API usability , 2011, 2011 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC).

[14]  Robert DeLine,et al.  Information Needs in Collocated Software Development Teams , 2007, 29th International Conference on Software Engineering (ICSE'07).

[15]  Lin Li,et al.  Obstacles in Using Frameworks and APIs: An Exploratory Study of Programmers' Newsgroup Discussions , 2011, 2011 IEEE 19th International Conference on Program Comprehension.

[16]  P. Mayring.  Qualitative content analysis: theoretical foundation, basic procedures and software solution , 2014 .

[17]  Wayne G. Lutters,et al.  Revealing actual documentation usage in software maintenance through war stories , 2007, Inf. Softw. Technol..

[18]  Sae Young Jeong,et al.  Improving Documentation for eSOA APIs through User Studies , 2009, IS-EUD.

[19]  J. McNally.  Self-Directed Learning, A Guide for Learners and Teachers , 1976 .

[20]  Martin P. Robillard,et al.  Creating and evolving developer documentation: understanding the decisions of open source contributors , 2010, FSE '10.

[21]  Rainer Koschke,et al.  On the Comprehension of Program Comprehension , 2014, TSEM.

[22]  Brad A. Myers,et al.  Improving API usability , 2016, Commun. ACM.

[23]  Martin P. Robillard,et al.  What Makes APIs Hard to Learn? Answers from Developers , 2009, IEEE Software.

[24]  Karen A. Schriver.  Dynamics in document design , 1998 .

[25]  Steven Clarke,et al.  What Makes APIs Difficult to Use ? , 2008 .

[26]  Janice Singer,et al.  How software engineers use documentation: the state of the practice , 2003, IEEE Software.

[27]  Philipp Mayring.  Qualitative Inhaltsanalyse : Grundlagen und Techniken , 2003 .

[28]  Martin P. Robillard,et al.  How API Documentation Fails , 2015, IEEE Software.

[29]  Brad A. Myers,et al.  Mica: A Web-Search Tool for Finding API Components and Examples , 2006, Visual Languages and Human-Centric Computing (VL/HCC'06).

[30]  R. A. Guillemette.  Usability in computer documentation design: conceptual and methodological considerations , 1989 .

[31]  Jeffrey Stylos,et al.  Usability Implications of Requiring Parameters in Objects' Constructors , 2007, 29th International Conference on Software Engineering (ICSE'07).

[32]  Janet Nykaza,et al.  What programmers really want: results of a needs assessment for SDK documentation , 2002, SIGDOC '02.

[33]  Steven Clarke.  What is an End User Software Engineer? , 2007, End-User Software Engineering.

[34]  Marco Aurélio Gerosa,et al.  Preliminary Empirical Identification of Barriers Faced by Newcomers to Open Source Software Projects , 2014, 2014 Brazilian Symposium on Software Engineering.

[35]  Miryung Kim,et al.  An ethnographic study of copy and paste programming practices in OOPL , 2004, Proceedings. 2004 International Symposium on Empirical Software Engineering, 2004. ISESE '04..

[36]  Janice Singer,et al.  Studying Software Engineers: Data Collection Techniques for Software Field Studies , 2005, Empirical Software Engineering.

[37]  Forrest Shull,et al.  Investigating Reading Techniques for Object-Oriented Framework Learning , 2000, IEEE Trans. Software Eng..

[38]  Vahid Garousi,et al.  Usage and usefulness of technical software documentation: An industrial case study , 2015, Inf. Softw. Technol..

[39]  Carolyn B. Seaman,et al.  The information gathering strategies of software maintainers , 2002, International Conference on Software Maintenance, 2002. Proceedings..

[40]  Clay Spinuzzi,et al.  Building More Usable APIs , 1998, IEEE Softw..

[41]  Christoph Treude,et al.  How do programmers ask and answer questions on the web?: NIER track , 2011, 2011 33rd International Conference on Software Engineering (ICSE).