Building Documentation Generators

ArieVanDeursen, TobiasKuipers.

In Proceedings International Conference on Software Maintenance ( ICSM 99). IEEE Computer Society, 1999. pp. 40-49.

Abstract

In order to maintain the consistency between sources and documentation, while at the same time providing documentation at the design level, it is necessary to generate documentation from sources in such a way that it can be integrated with hand-written documentation. In order to simplify the construction of documentation generators, we introduce IslandGrammars, which only define those syntactic structures needed for (re)documentation purposes. We explain how they can be used to obtain various forms of documentation, such as data dependency diagrams for mainframe batch jobs. Moreover, we discuss how the derived information can be made available via a hypertext structure. We conclude with an industrial case study in which a 600,000 lines of code COBOL legacy system is redocumented using the techniques presented in the paper.

http://www.cwi.nl/~arie/papers/icsm99.pdf, http://www.cwi.nl/~arie/papers/icsm99/index.html