Judicious: API Documentation for Novices
summary
A web-based API documentation system for novices that shows one name at a time, uses diagrammatic function boxes and distinct icons for constants, and gradually reveals types, optional and variadic parameters; it explicitly highlights side effects and generates docs for functions defined in student code so examples and signatures match classroom code. Integrated into an editor, open source, piloted with middle/high school classes, and positioned for formal empirical evaluation.
AI-written summary · about
chapters (15)
- 0:00Judicious API documentation
- 2:50Gradual explanations in education
- 5:19Gradual docs for novices
- 7:01Multiple function representations
- 8:49Side effects and misconceptions
- 10:16Built-in functions and docs bar
- 11:20Variadic functions documentation
- 12:01User-defined functions in docs
- 13:02Platform and open-source
- 14:55Q&A: Graphical representation
- 16:17Q&A: Manual vs generated
- 17:23Q&A: Examples and GitHub
- 18:05Q&A: Debugging mistakes
- 18:47Q&A: Judicious vs professional docs
- 19:50Summary and future
related talks
42mGood APIs don't need a tutorial
35mOpenAPI for Documentarians
46mDocumentation That Runs: Bridging Code, Prose, and Interactivity
20mThe Curse of Documentation
25mDo you know who's reading your Docs?
48mBeyond Words: Crafting User-Friendly Documentation
04mSome Quick Thoughts about Documentation
20mUser Brainpower vs. AI Blind Spots in API Docs