Description
The success of an API crucially depends on how well its documentation meets the information needs of software developers. But what information do developers need? What information do they want, and what information are they actually using when starting to learn a new API and solve programming tasks with it? In this talk, I will present the results of some empirical studies I conducted with my team to better understand the information needs of software developers. One the one hand, we ran more than 20 semi-structured interviews with junior and senior developers and asked them – among other things – to tell us about the questions they raise first when approaching a new API, the type of documentation they look for, and general expectations and experiences regarding API documentation. Key findings derived from the interviews were then followed up on by a standardized survey in which more than 110 developers participated. Our second study took a different approach. Instead of asking developers what they find important about API documentation, we asked them to solve a few tasks on a simple (REST)-API that was unfamiliar to them. The goal of this study was to observe how the developers approach the tasks and which pieces of the documentation provided with the test API they actually use. Besides presenting the design and main findings of our studies, I will also discuss implications the results may have regarding the contents, structure and design of API documentation.