Code Guide - Interactive Explanations of Example Code

I find it difficult to maintain example code for an API. Examples are often in tutorial documentation in a content management system separate from the source code control system. Example code is often duplicated, because the tutorials expose API features bit by bit, often in a different order than is required in the code, and also shows the entire example program. As a result, it's hard to find, fix and verify all relevant example code when we make API changes.

I've written an experimental tool, called Code Guide, to try and address this problem. Code Guide turns special comments in example code into interactive HTML documentation that leads the reader around the code, explaining what different parts do. The example code can be held in the same source code control system as the API and so versioned and tested along with it.

Code Guide is a kind of opposite of Literate Programming. In Literate Programming you write explanatory documentation first, introducing fragments of code within the documentation in the order that makes most sense for the explanation. A tool extracts the code and reorders it so that it can be interpreted or compiled. Code Guide, on the other hand, puts documentation into comments in the source and the tool generates documentation from those comments. The comments control the order in which parts of the code are explained to the reader, so you can guide the reader through the code in an order that most helps explain what the code is doing. However, people are also likely to read example code when they download a project release or clone a project's Git repository, so the documentation comments in the code can hopefully still be understood even without generating HTML from them.

Here are some examples of the Quick2Wire Python API:

What do you think? Does this make for useful example code? Comments welcome.

Mistaeks I Hav Made

Code Guide - Interactive Explanations of Example Code