Judicious: API Documentation for Novices

Programmers frequently consult API documentation to learn how to use libraries, both those included with a programming language and those offered by third parties. Beginner programmers also have this need but struggle to browse professional documentation systems, which are aimed at experienced programmers. Educators sometimes try to patch this problem by writing simplified, ad hoc educational documents as a surrogate for a documentation system. This paper presents Judicious, an API documentation system explicitly designed for novice programmers. It allows retrieving the documentation for one name at a time; offers a clear and distinctive visual representation of functions and constants; gradually presents more information such as types, optional and variable-length parameters for functions; highlights functions with side effects; and instantaneously generates documentation also for functions defined in student code. Judicious's design builds on prior research in the learning sciences and programming languages. The gradual disclosing of information matches the progression of increasingly larger subsets of programming languages. The diagrammatic representation, the clear distinction between functions and constants, and the pinpointing of side effects aim to address known novice misconceptions. The system is integrated into a code editor and is publicly available as a web platform.