Improving API Reference Documentation: A Cognitivist Approach to Design and Evaluation

Abstract

Using API reference documentation is a crucial task for developers, especially when working with less popular programming languages and libraries. Although such interfaces are ubiquitous, there has been limited research into their effectiveness. The role of working memory in the comprehension of complex information at scale is also not well understood. Here, we introduce an interactive interface for viewing and exploring reference documentation from a cognitive science perspective. Our interface features a tabular layout with type sorting and search features, allowing users to see different individual functions more efficiently. We implemented this documentation interface for the functional programming language OCaml and performed a within-subjects study against existing OCaml documentation. We investigated the impact of working memory on the performance of these interfaces. While users prefer our novel interface qualitatively, there are only marginal improvements in function lookup time and understanding. Further, we show that working memory is a strong predictor of function lookup time across both interfaces, suggesting that lookup times may increase during high cognitive load situations. Our results highlight the importance of leveraging cognitive science insights in future human-computer interaction research.