Lambda the Ultimate

First, high-level system documentation doesn't seem to have a place. It often ends up as a long prelude to the code, which, while useful, doesn't strike me as literate programming. By analogy, I think the reason for this is that it is difficult to give a high-level description of a forest (e.g. it's location between a river and a mountain ridge) by labeling each tree. This is a symptom of one of the central difficulties in programming: managing dependencies which run counter to your chosen system decomposition. It has the potential to occur wherever a particular section of code can conceivably be "grouped" in more than way within the system.

Second, I believe the need for low-level documentation beyond basic commenting results mostly from the deficiencies in the underlying programming language or of the programmer's allergy to descriptive naming conventions. An oft-occurring example of the former would be the need to document which arguments of a procedure are for input, which for output, which are changed, etc in many languages. I'll leave the later to your imagination.

For the most part, I am of the opinion that literate programming is a good strategy to manage an inadequate language, but does little to help a programmer cope with the esential complexity of larger systems. Nevertheless, here are three aspects o literate programming that I find very insightful.

First, program code should be presented to the programmer differently than it is presented to the compiler, as they are very different agents who interact with code in very different ways.

Second, all of the dependencies, including documentaion dependencies, should be presented to the programmer when s/he is working with a section of code.

Last, the code and documentation, considered together as a combined whole, should be as nonredundant as possible. For example, when the name of an API procedure is modified "in the code," the update should be automatically reflected in the documentation.