Designing API documentation for novice developers

• Main Author: Skøien, Johannes
• Format: Dissertation
• Language: English
• Subjects: API; API documentation; API usability; DHIS2; novice developers; platform development

Application Programming Interfaces (APIs) play a significant role in the soft- ware development-process, as they provide access to useful functionality and endpoints in a broad spectrum of relevant systems. Through this thesis, the needs and experiences of novice API developers are studied, in order to identify the needs of said users regarding API documentation, compared to the existing knowledge obtained by studying more experienced users. Even though there are similarities in the needs, there are also some differences that needs to be considered. The thesis has primarily focused on two elements of the documentation: content and organizing, in order to identify areas of improvement regarding the perception for users without necessarily much preliminary experience using APIs. By looking at what information is presented, as well as how it is presented, weaknesses in current documentation can be identified and improved to better suit users with different experience levels. Content and organizing are also often connected, making them natural to view together to gain an overall understanding. The study has been conducted as a qualitative study, where a combination of interviews and observations has been used to identify irritations, obstacles and possible improvements when developing with APIs. 15 participants with varying backgrounds have been interviewed in order to gain insight in the mentioned areas from different perspectives. In addition to this, observations of users of the DHIS2 Web API have been conducted to understand actual processes and development, with the aim to gain insight in approaches to solving current experienced problems in actual processes. Considering facilitating learning and development for a broad range of experience can be beneficial for an API to be perceived as useful by more users. The thesis identifies six points of recommendation for practice in order for API documentation to be useful and intuitive also for novice users. These points are to 1) Consider combining a guide- and encyclopedia-approach, 2) Connect examples to use cases to explain how concepts are used in practice, 3) Make examples interactive, 4) Keep descriptions short and precise, 5) Identify and prioritize presenting the most relevant information first and 6) Gather relevant resources in categories. By employing these points of focus when designing documentation, it is possible that novice users can find the documentation easier to use, thus are more likely to s