Research Abstracts - 2006

SourceBrowser: A Versioned Collaborative Browser for Development Repositories

Punyashloka Biswal & Dimitrios Vyzovitis

Specifications and documentation associated with a software project tend to grow stale and out of date over time. This happens partly because there is no link between corresponding semantic entities in documentation and code. This problem is particularly acute for <#part type="text/html" buffer=scrb-abstract.html disposition=attachment description="srcb Abstract"> <#/part> newcomers to a development team, who are faced with the choice of reading through volumes of documentation without knowing which parts of it are trustworthy, or ignoring documentation altogether and relying on source code alone.

We are inspired in part by literate programming systems, which were introduced by Donald Knuth[1] as a way to combine source and documentation into beautiful, human-readable texts. Unfortunately, Knuth's vision of a monolithic software distribution that is small enough to describe in article form seems impractical today, and we believe that a browseable and editable wiki of code and documentation is the right solution.

Our aims are:

• to provide an infrastructure for naming and linking semantic entities, especially those that span multiple code and/or documentation artifacts;
• to let developers browse and update documentation using a hypertext interface that exploits the linked structure established above; and
• to use information about the version skew between linked entities to provide an estimate of the reliability of a piece of documentation.

References:

[1] Donald E. Knuth. Literate Programming. In The Computer Journal, pp. 97, Vol. 27, Issue 2 (May 1984).