Generating Consistent Program Tutorials

In this paper we present a tool that supports construction of program tutorials. A program tutorial provides the reader with an understanding of an example program by interleaving fragments of source code and explaining text. An example program can for example illustrate how to use a library or a framework. We present a means for specifying the fragments of a program that are to be in-lined in the tutorial text. These in-line fragments are defined by addressing named syntactical elements, such as classes and methods, but it is also possible to address individual code lines by labeling them with source markers. The tool helps ensuring consistency between program tutorial and example programs by extracting fragments of source code based on the fragment specifications and by detecting when a program tutorial is addressing program fragments that do not exist. The program tutorials are presented as online resources, providing navigation to other documents, such as reference manuals, other tutorials, internal documentation, and also to a presentation of the source code fragment in its original context. We have produced three example program tutorials in order to get some experience with the tool, and we see potential in using the tool to produce program tutorials to be used for frameworks, libraries, and in educational contexts