Workshop W5

TITLE: Documentation for Software Engineers: What is Needed to Aid System Understanding?

LEADER(s): Dennis Smith, Software Engineering Institute, Carnegie Mellon University, USA; Bill Thomas, Software Engineering Institute, Carnegie Mellon University, USA; Scott Tilley, University of California, Riverside, USA

KEYWORD(s):  documentation, software engineering, program understanding

CONTACT PERSON: Scott Tilley

CONTACT E-MAIL: stilley@cs.ucr.edu

ABSTRACT:

Software engineers rely on program documentation as an aid in understanding the functional nature, high-level design, and implementation details of complex applications. Unfortunately, the documentation for most software systems is usually out-of-date and therefore cannot be trusted. Without such documentation, engineers are forced to rely solely on source code. This is a is a time-consuming and error-prone process, especially when one considers the amount of information assimilation and domain mapping that is required to understand the architecture of a large-scale software system.

One way of producing accurate documentation for an existing software system is through reverse engineering. Indeed, there are several highly-specialized conferences that focus on the constructions of reverse engineering tools to aid program understanding. These tools create ancillary documentation, provide graphical views of the software system, and generally attempt to augment the knowledge hidden in the source code with secondary structures. However, reverse engineering tools remain relatively underused. Perhaps one reason for their slow adoption rate is that the type of information these tools produce is not the type of information that the software engineer needs to complete his or her task.

It is almost axiomatic that high-quality program documentation can greatly aid the engineer in such a maintenance task by provided multiple and complimentary views of the software system. However, the truth is that no one really knows what types of documentation are truly useful. This highlights the underlying problem with (semi-)automatic document creation processes: if no one understands what is needed, it should come as no surprise that tools that produce this type of documentation are rarely used by real-world software engineers. This situation raises several fundamental questions:

•  What types of documentation does an engineer need? What formats should it take? For example, inline or linked textual commentary? Graphical views? Multimedia?
•  Who should produce the documentation? The developers? The testers? The technical writers? And who should maintain the documentation once it is produced?
•  When should the documentation be produced? During development? After the product has been deployed? There is a school of thought that “just in time” documentation might prove more useful than providing all the documentation at once. While the typical problem is a lack of documentation, there can also be a problem of too much documentation. Or, more accurately stated, too much documentation not in the correct format for the task at hand.
•  How should the documentation be written? Are there particular styles of writing that make software documentation more understandable? Is a minimalist approach better? Might a “wizard”-like agent be used to guide personalized content creation?
•  Why should documentation be produced at all? Recent light-weight processes, such as Extreme Programming, do away with documentation in its entirety. Is this a better way of solving the underlying issue, which is helping software engineers understand code?

This two-hour workshop will explore these issues. It is hoped that the juxtaposition of a traditional SIGDOC audience with software engineering researchers and practitioners will provide new insights into the problem. The workshop will encourage the exchange of views and expertise on established and innovative ways of structuring program documentation to aid system understanding by software engineers.

The workshop will include the presentation of the research paper “Documenting Software Systems with Views II: An Integrated Approach Based on XML,” which is included in the conference proceedings.

Last modified October 28, 2001 by Scott Tilley.