Application Programming Interfaces (APIs) play a crucial role in modern software engineering. However, learning to use a new API often is a challenge for developers. In order to support the learning process effectively, we need to understand how developers use documentation when starting to work with a new API. We report an exploratory study that observed developers while they solved programming tasks involving a simple API. The results reveal differences regarding developer activities and documentation usage that a successful design strategy for API documentation needs to accommodate. Several guidelines to optimize API documentation are discussed.

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.