Documentation Generation

Program-Transformation.Org: The Program Transformation Wiki
Deriving (on line) documentation from source code. The purpose is to help maintainers or developers understand the system they are working on.

The article BuildingDocumentationGenerators lists four criteria that technical documentation should adhere to:

  1. Documentation should be available on different levels of abstraction.
  2. Documentation users must be able to move smoothly from one level of abstraction to another, without loosing their position in the documentation (zooming in or zooming out).
  3. The different levels of abstraction must be meaningful for the intended documentation users.
  4. The documentation needs to be consistent with the source code at all times.

Analyzing sources, finding different levels of abstraction through ReverseEngineering, and presenting these using graphs and hypertext is a way to get as close as possible to meeting these criteria.

See also: DocGen, RigiSystem, ArchitectureExtraction, NDoc, JavaDoc?, Imagix 4D

The University of Southern California has developed a tool called Media Doc that generates software explanations to support ProgramUnderstanding. The explanations combine text, graphics and animation, and should replace conventional documentation.

Media Doc views the process of explaining software as a series of software inquiry-explanation cycles with Media Doc providing explanations on demand to an engineer's inquiries. Explanations are generated based on profiles of the user's tasks and expertise. The user can pose a series of queries either by directly entering a query or by interacting with Media Doc via the Task Model interface. Media Doc either generates an explanation that directly answers the query, or reformulates the query as a new subtask.

Answers to queries are generated from a library of dynamic templates that combine text and graphics. These templates are authored in Media Doc's presentation authoring language, and may include sections that are automatically generated from code analysis tools and behavior traces.


CategoryReverseEngineering | Contributors: ArieVanDeursen