Optimizing API Documentation

Abstract

The growing importance of APIs creates a need to support developers with effective documentation. Prior research has generated important findings regarding information needs of developers and expectations they form towards API documentation. Several guidelines have been proposed on the basis of these findings, but evidence is lacking whether such guidelines actually lead to better documentation. This paper contributes the results of an empirical test that compared the performance of two groups of developers working on a set of pre-defined tasks with an API they were unfamiliar with. One group had access to documentation which was optimized following guidelines for API documentation design proposed in the literature whereas the other group used non-optimized documentation. Results show that developers working with optimized documentation made fewer errors on the test tasks and were faster in planning and executing the tasks. We conclude that the guidelines used in our study do have the intended effect and effectively support initial interactions with an API. CCS CONCEPTS • Software and its engineering → Software creation and management; Software post-development issues; Documentation; • Human-centered computing → Human computer interaction (HCI); HCI design and evaluation methods; User studies.

Assessing Real-World Applicability of Redesigned Developer Documentation for Certificate Validation Errors

“…Nevertheless, the proposed system would not scale easily as it requires custom-tailored patches for each API. A later study by Meng et al [20] investigated the effects of improved documentation on API usage. In a comparative study, half of the participants interacted with documentation optimized following the design guidelines proposed in the literature, with the other half seeing only the non-optimized version.…”

“…There have already been some academic attempts to solve similar issues. Gorski et al [15] investigated the potential of API-integrated security advice and Meng et al [20] looked into adjusting the documentation content and structure along the published usability guidelines. We aim to test the real-world applicability of more usable certificate validation documentation, redesigned following existing guidelines.…”