Documentation Generation as Information Visualization

TL;DR

This paper analyzes automatic documentation tools as a form of information visualization, proposing design principles to enhance their usability for developers seeking API information.

Contribution

It introduces a visualization-based analysis of auto docs and suggests improvements for better supporting search and scanning of API details.

Findings

Auto docs serve as reference tools for API primitives.

Enhanced visualizations can improve search and scanning.

Design principles can guide better auto doc interfaces.

Abstract

Automatic documentation generation tools, or auto docs, are widely used to visualize information about APIs. However, each auto doc tool comes with its own unique representation of API information. In this paper, I use an information visualization analysis of auto docs to generate potential design principles for improving their usability. Developers use auto docs as a reference by looking up relevant API primitives given partial information, or leads, about its name, type, or behavior. I discuss how auto docs can better support searching and scanning on these leads, e.g. by providing more information-dense visualizations of method signatures.