Integrated Documentation and Elucidative Programming

Kurt NÝrmark and Thomas Vestdam ©
Department of Computer Science
Aalborg University


Index References Contents
Theses slides are intended for the Nouhauz talk on Integrated Documentation and Elucidative Programming at Aalborg University, January 31, 2001. The talk is given by Kurt NÝrmark ( and Thomas Vestdam (

We start by explaining our approach to documentation. We identify three different kinds of integration between documentation and program. One of these correspond to literate programming (ala Knuth) which we briefly explain. Another is the starting point of elucidative programming.

Next we explore elucidative programming in some depth. We conclude with summaries of practical experience from both education and industry.

Plan of the talk
Slide Note Contents Index
On this page we outline the plan of the talk.

  • Introduction, motivations, and ideas - Kurt NÝrmark

    • Background - including literate programming

    • Characteristics of Elucidative Programming

    • The elucidative programming tools

      • Tool philosophy

    • Perspectives and concluding remarks

  • Break

  • Demo of the Java Elucidator - Thomas Vestdam

  • Experiences

    • Educational - Thomas Vestdam

    • Industrial - Kurt NÝrmark

  • Discussion

Overall Observations

Which kind of documentation
Slide Note Contents Index
We start with a few - but important overall observations concerning our approach and our work.

There are many kinds of documentation: analysis documentation, design documentation, interface documentation, internal program documentation, user-oriented documentation, ...

  • We focus on internal program documentation

  • Integrated documentation

    • Addresses the connection between program and documentation

    • Several possibilities will be explored

  • Our tools are probably useful in any situation, where there is a need to write about a program

Views on documentation
Slide Note Contents Index
There are many different views on documentation, including common attitutes that are reconfired among programmers to such a degree, that most of us belive they are true.

Many programmers are reluctant to read and write program documentation

  • Documentation of program understanding (DOPU)

    • Programming requires understanding of both the problem and its solution

    • We cannot afford to forget the understanding once established

    • It is expensive to reestablish the understanding if its forgotten.

We see documentation as an investment in more high quality programs

We hypothesize that the investment is payed back during the life time of the program

We call for a professional attitude towards this problem

Integrated program documentation
Slide Note Contents Index
We will here explore the possibilities of integrating programs and written program documentation

There are several ways to integrate program and documentation

  • The documentation is embedded in the program

    • Conventional program comments

    • The program is the main structure

  • The program is embedded in the documentation

    • Literate programming

    • The documentation is the main structure

  • The program and the documentation are separated, but connected via links

    • Hypertext approach

    • The starting point of elucidative programming

Literate Programming

An example of a literate program
Slide Note Contents Index
For those who do not have a background in literate programming we here show an example of a simple literate program. The program is in Danish, but it should nevertheless be possible to get a general understanding of the approach.

In order to be concrete we briefly present an example of a literate program and the source from which it is generated


Internal structure of a literate program
Slide Note Contents Index

Internally, a literate program is made by a hierarchical program and a linear document structure

Figure. The internal literate programming structure.

Figure. The program as assembled from the WEB above.

Literate Programming ala Knuth
Slide Note Contents Index
Here we will briefly describe an important background and inspiration, namely Knuth's ideas of literate programming.

Knuth invented literate programming in order to explain and publish his programs in articles and books

  • Characteristics of literate programming:

    • A program is structured according to its explanation

    • The distance between the documentation and the program is small

      • Physical proximity

      • The pieces of program 'live in' the documentation

      • It becomes 'necessary' to explain everything

That it becomes 'necessary' to explain everything has to do with the observation that we need to create an explanational context in which to place a piece of program. Now it is there, it is natural to write something that makes sense - something useful.

Literate programming is typically supported by tools in the WEB-family

Problems with literate programming
Slide Note Contents Index
Elucidative programming is meant to be an alternative to WEB-like literate programming. Therefore it is natural to identify a number of problems with classical literate programming which we attempt to remedy in our variation of literate programming.

  • The Program is embedded in the documentation
    Only few programmers want to split their programs in fragments and to organize these as parts of the documentation

  • Language mixing
    The mix of three languages in a single document is not attractive

    • Documentation language, programming language, and interconnection language

    • Reading and comprehension problems

  • Extra level in error handling
    Error handling is more complicated because the errors need to be mirrored in the new source program

    • Reasonable solutions exist

  • Paper orientation
    Most existing tools are oriented towards printed paper presentation of the literate program

Elucidative Programming

The meaning of the word
Slide Note Contents Index
The verb 'elucidate' may not be part of the working vocabulary of many Danes. Therefore we introduce the meaning of the word on this slide

To elucidate is

"to make clear or plain, especially by explanation"

"to throw light on something complex"

Elucidative Programming
Slide Note Contents Index
At this place we introduce elucidative programming. We here describe a number of key properties of the documentation approach.

Elucidative programming is meant to remedy some of the identified problems with literate programming

  • Elucidative programming highlights:

    • User interface

      • Present the program and the documentation side-by-side in an Internet browser

    • Leave the program "in peace"

      • Does not impose any requirement on the organization of the program in files or directories

    • Address existing abstractions from the documentation

      • Does not rely on separately named program fragments

    • Supported by the development environment

      • Requires specialized editor functionality

We will return to all of these items later in the presentation

An example of an elucidative program
Slide Note Contents Index
In order to be concrete we will here give an example of an elucidative program. This program is akin to the program which is discussed in the SIGDOC paper

The example illustrates the development of a small program that converts a large integer, representing the number of seconds elapsed since January 1, 1970 to a conventional date and time structure


Strong and weak points
Slide Note Contents Index

We see both strong and weak points in the elucidative approach

  • Strong points

    • The possibility to explain transverse themes, such as design patterns

    • The use of navigational proximity instead of physical proximity

  • Weak points

    • Difficult to maintain an elucidative program

    • Reading in a browser - writing in the development environment

The elucidative programming model
Slide Note Contents Index
This page describes a number of important concepts behind the elucidative programming model.

  • Entities

    • Named abstractions on the program side

    • Sections and subsections on the documentation side

    • A naming scheme that allows us to address the program entities from the documentation

  • Relations

    • A doc-prog relation which connects explanations with program entities.

    • A prog-prog relation which connects applied and defined name occurrences

    • A doc-doc relation which connects explanations across the hierarchical documentation structure

  • Source markers

    • Represent positions in a program which we want to address in the explanations

  • Documentation bundle

    • An aggregation of programs, documentation texts, and additional properties (e.g., processing options)

The source format of the documentation
Slide Note Contents Index
When the programmer works with a literate program the source format of the documentation is of particular interest. This format is important because it constitute the words and lines actually written by the programmer. In addition, the programmer will spend much time reading parts of the documentation in this format. Therefore the properties of the format matters. This page is related to the Scheme elucidator only.

  • Scheme: A simple, specialized markup is used for the overall structure, the relations, and the source markers

    • Non-obstructive, discrete, and terse

    • It is relatively easy and attractive to read the documentation in the editor

  • Java: An XML markup language is used for the overall structure, the relations, and the source markers

    • Standard, and general markup language

    • Can be processed via a number of different tools

  • HTML is used for additional markup purposes

    • Avoids proliferation of languages with similar purposes

    • The mixing of markup styles is not aesthetically pleasant


Tool Overview
Slide Note Contents Index
There are three important tools in an elucidative programming environment. Of these, a standard Internet browser counts for one. The others are the editor used for programming and documentation, and the tool which produces the underlying browser format.

  • Our elucidative programming environment contains the following tools:

    • An editor which is used for both programming and documentation purposes

    • An elucidator which converts programs and documentation to HTML pages

    • A internet browser which is used for presentation of the elucidative program

The elucidator plays the role of the literate programming weave tool

In elucidative programming there is no need for a tangle tool

The editor tool
Slide Note Contents Index
The editor tool for the elucidator plays a major practical role. It is important that the programmer can continue working in his favorite environment. We will assume that our programmers use Emacs. Therefore we chose be augment the Emacs text editor with elucidator support.

It is of major importance to provide for easy and flexible editor support of elucidative programming

We have augmented Emacs with elucidative facilities

  • Design objectives:

    • The editor applies a split-screen layout in the same way as the browser

    • The editor's support of the programming language is available in non-changed form

    • The creation of the doc-prog and doc-doc relations is nursed in particular

    • The major navigation possibilities - as supported by the browser - are also present in the editor

    • Emacs keeps the documentation bundle together by a special marking of the buffers involved

The elucidator tool
Slide Note Contents Index
The elucidator tool produces the HTML pages to be shown in a browser. In addition, the elucidator tool makes a number of data structures used by the editor to gain knowledge about the documentation bundle.

The elucidator is the tool that processes a documentation bundle in order to produce an elucidative program

  • Tasks of an elucidator

    • Abstraction

      • Parses the documentation and the program

      • Extracts knowledge about program and documentation entities

    • Synthesis

      • Generates the HTML pages with links that represent the three kinds of relations between entities

The synthesis part may be static, or it may be carried out by the WWW server on a dynamic basis

The browser tool
Slide Note Contents Index
The browser tool of an elucidative programming environment is just a standard, modern Internet browser. On this page we emphasize the typical frame layout used by an 'elucidative browser'.

The browser tool is realized by an ordinary Internet browser

  • Characteristics of the browser

    • The "T layout" of the browser window, supporting a side-by-side alignment of documentation and program

Figure. The basic frame layout of an Internet browser that presents an elucidative program


Tool Integration
Slide Note Contents Index
Tool integration is a key issue when two or more program development tools are used together. On this page we discuss integration issues of the tools in an elucidative programming environment.

The current integration of the editor and the elucidator is simple and rather primitive

  • Cooperation between the elucidator and the editor

    • The elucidator abstracts information from the documentation bundle which the editor can read on demand

    • The editor is always a step behind with respect to knowledge about the current documentation bundle

    • The elucidator can be activated very smoothly from the editor

Mutual activation of the browser from the editor - and vise versa - would be a major practical improvement

Tool philosophy
Slide Note Contents Index
Here we will discuss possible and different tool organizations. We call it 'tool philosophy'. Our point is not to force the programmer into a specialized environment for authoring of program documentation. We go for documentation enabling of existing environments. In our experience, programmers are rather conservative, and most of them want to continue working in their favorite environments. There must be major advantages in a new environment in order for the programmers to shift.

  • Possible tool organizations:

    • Provide a brand new tool with an embedded editing environment for elucidative programming

      • Like Sametinger's Dogma System

    • Introduce a separate processing tool and augment an existing editor with knowledge about elucidative programming

      • Typically a Unix and Emacs solution

    • Include elucidative aspects into current integrated programming environments

      • Long term goal - requires industrial collaboration

Programmers do not want to be forced into a new and specialized editing environment

A broader perspective on the use of elucidative programming
Slide Note Contents Index
Here we will list a number of potential areas which we expect can be supported by the elucidator.

Most documents that need to address program units or program details will be able to benefit from the ideas of elucidative programming

  • Documents with 'an elucidative potential':

    • Diaries and logs

    • Written code reviews and code walk throughs

    • Program tutorials

    • Design documents

    • Maintenance documentation

Research issues
Slide Note Contents Index

A number of additional documentation issues warrant future research

  • Research issues

    • Maintenance of elucidative programs

      • Versioning

    • Cooperative elucidative programming

    • Structure of documentation

    • Refined tool support

We want to deal with some of these as documentation patterns

Status and Conclusions
Slide Note Contents Index
We conclude this presentation with some brief accounts on the status of our work.

  • Contributions:

    • Use of hypertext concepts for internal program documentation

    • A serious attempt to present programs and their internal understanding on the Internet

    • A renewal of the tool ideas for literate programming

  • Status

    • A prototype of an elucidative Scheme environment exists

    • Two different versions of elucidative Java prototype environments exists

      • Version 1 supports a single essay node with explanations

      • Version 2 supports a much richer structuring of the explanations

    • Both limited educational and industrial experience

      • Discussed after the break


Java Elucidator Demo

The Java Elucidator
Slide Note Contents Index

The Java Elucidator has been developed by five master students

The first version is similar to the Scheme elucidator at the conceptual level

The second version supports a more structured documentation approach

  • Observations about the Java elucidator:

    • The naming scheme used to address program units from the documentation is rather complex

      • It involves a lot of details to make a doc-prog link

    • Relies on an abstraction process which populates a relational database with program and documentation information

    • The synthesis task is done dynamically by the WWW server

      • It is also possible to generate a static set of HTML pages

The Design of the Java Elucidator
Slide Note Contents Index
On this page we will illustrate the overall design of the Java Elucidator.

Figure. The design of the Java Elucidator


Educational experience
Slide Note Contents Index

The Java Elucidator has been tried out by a group of Dat1 students in the fall of 2000

  • We have examined the usefulness of Elucidative Programming in seven different areas

The seven areas
Slide Note Contents Index

  • Review situations

  • Confidence of knowledge about software

  • Further confidence through inclusion of tests

  • Maintenance of Elucidative Programs is manageable during development

  • Programs become less error prone

  • Ease of maintenance

  • Generally, the tool is useful

Industrial experience
Slide Note Contents Index

The Java Elucidator has been used by three programmers in Danish Java software house.

This experiment was carried out by Max R. Andersen and Claus N. Christensen

  • Feedback:

    • Elucidative Programmig is applicable in industry

    • The tools were addapted - but they probably need improvements

      • Problem with two representations (development, browser).

      • Abstraction requires that the program can be compiled

    • A group communication potential was revealed

      • Not easy to capture and represent verbal communication

Industrial quotes
Slide Note Contents Index

  • "Elucidative programming is a paradigm which fits the lightweight process we use"

  • "I believe that if we did not have such an Elucidator tool, then in the best case this would be scribbled down on a piece of paper, which would eventually be scrumpled up "

  • "If I was to write the documentation completely isolated from the source code - well then it would have been completely useless - so it has to be done on the source code in some way"

  • "At first it feels like: this takes time. But I do not think this is necessarily the case"

  • "This is not end user documentation, and it is not polished analysis and design. It is actually very intimate, so on that set it reminds me a lot of this diary I have written from time to time"

  • "It is probably something you has to integrate in the process... to get it on your mind, as a daily activitiy, as a natural part, right?"

  • "I do not dare to mess with this, but I can always make a note about it - if I one day want to change something"

Further Information

WWW resources
Slide Note Contents Index

These slides will be available from the elucidative programming home page.


Collected references
Contents Index
An example of the literate program source program (section 5) - in Danish
A literate Life Program in Pascal - NuWeb - in Danish
The Time Conversion example (Java - Only in Netscape)
An everyday example: The annotator tool (Scheme)
The Time Conversion example (Scheme)
An excerpt of the time conversion documentation source - Java
An excerpt of the time conversion documentation source - Scheme
The Time Conversion example


Integrated Documentation and Elucidative Programming
Course home     Author home     About producing this web     Previous lecture (top)     Next lecture (top)     Previous lecture (bund)     Next lecture (bund)     
Generated: April 24, 2001, 16:51:33