Next / Previous / Shipman's Home Sweet Homepage / Site map

Lightweight literate programming

The purpose of literate programming is to erase the distinction between source code and documentation. The author writes a single narrative, describing algorithms, data structures, and design philosophy, and the source code is embedded at appropriate locations in this narrative.

The idea is that you do not document programs (after the fact), but write documents that contain the programs. [John Max Skaller]

The primary early proponent of literate programming was Dr. Donald E. Knuth. For a good summary of the history and current work in literate programming, see the Literate Programming website.

The author was inspired by recent work of his colleague, Dr. Allan M. Stavely, in devising lightweight approaches to literate programming. We have a peer-reviewed journal article on the subject:

Stavely, Allan, Lynda Walsh, and John Shipman. Lightweight literate programming: a documentation practice. Technical Communication 55(1), Feb. 2008.

In the author's current toolchain, the input is written in a slightly customized dialect of DocBook. Automated tools produce the two primary forms of output:

Following is a list of numerous completed projects done by the author in the literate style, with comments about points of interest in that product. All these projects also use The Cleanroom software development methodology.

Python: Basic examples

Tkinter: Graphic user interfaces in Python

XML: Python applications with eXtended Markup Language

XSL-FO: Generating PDF with XSL Formatting Objects

Literate programming of LaTeX templates

Zoological applications of Python

Projects for the New Mexico Tech Computer Center (TCC)

Next: The Cleanroom software development methodology
See also: Software engineering and software tools
Site map
John W. Shipman,
Last updated: 2014/05/09 20:39:32