Automatic documentation generation: Including examples

Abstract

Good documentation is critical for user acceptance of any system, and empirical studies have shown that examples can greatly increase effectiveness of system documentation. However, studies also show that badly integrated text and examples can be actually detrimental compared to using either text or examples alone. It is thus clear that in order to provide useful documentation automatically, a system must be capable of providing well-integrated examples to illustrate its points.

Previous work on example generation has concentrated on the issue of retrieving or constructing examples. In our work, we looked at the integration of text and examples. We identified how text and examples co-constrain each other and showed that a system must consider example generation as an integral part of the generation process. We implemented a system capable of producing documentation that integrated text and examples.

This work was carried out with Vibhu Mittal, when both Dr. Mittal and the author were at the University of Southern California/Information Sciences Institute. The author gratefully acknowledges support from NASA-Ames grant NCC 2-520 and DARPA contract DABT63-91-C-0025.