Home

Everybody complains about the weather, but nobody every does anything about it. Except him - he never complains about the weather.

-- David Mamet, "Squirrels"

Substitute "documentation" for "weather" and you get a pretty good description of "the documentation problem" in software development culture. Everybody laments the dearth of good documentation, but very few do much of anything about it. Spotty documentation seems to be endemic to software, especially open source software. On the other hand, who is to say what counts as "good", or even "adequate" documentation? What experts find adequate beginners may find useless, and what beginners find wonderfully helpful experts may find annoying.

The primary purpose of the Code Genres project is to explore the nature of technical (specifically software) documentation and its relationship to code, computation, etc.. A secondary goal is to generate specific tools and techniques in the service of good software documentation.

The name of the project is taken from Mikhail Bakhtin's small masterpiece "The Problem of Speech Genres". The concept of genre comes from literary studies; examples of literary genres include Greek Tragedy, the Epic, the Petrarchan Sonnet, and Elegy. Less lofty literary genres include the nursery rhyme, the limerick, and the newspaper article.

But the concept of genre extends far beyond such well-known exemplars. Very roughly speaking, a genre is characterized by a set of norms (aka "traditions") governing the form of "instantiations" of the genre. Thus even such humble literary productions as the shopping list, the traffic ticket, and school report card can be viewed as genres. Bakhtin's brilliant essay applied the concept of genre to speech performances of all kinds: not only those with a recognizable genre, such as political speeches and theatrical performances, but even the most mundane and routine speech performances, such as greetings, military commands, and ordering food in a restaurant. In order to be recognized as performances of a certain kind, they must conform to the norms of the genre: a military command that is offered with a whimper and a "please?" would just confuse the troops, since what counts as a command (in the military) is determined by certain syntactic forms (imperative mood, no "please") as well as non-verbal form - a firm tone, etc.

The concept of code genre builds on these notions. The various forms of documentation - the User Guide, the Technical Reference Manual, the Tutorial, etc. - are easily construed as literary genres: their form is governed by a set of norms (conventions, expectations, etc.) that has emerged gradually in the course of the history of computation. Those norms may be relatively loose, but they are norms nonetheless.

But code itself is a kind of literary genre. Programs have certain characteristic forms; these forms are only partially determined by the formal syntax of the language. For example, norms have emerged governing the naming of certain classes of variables; the paradigmatic case is the use if i as the name of an index variable used for looping.