Redocumenting software systems using hypertext technology

Abstract

Software maintenance is a perennial problem that will be with us for many years. This view is confirmed by the number, of existing Software systems that require maintaining and thdr predicted lifespan. The majority of software maintenance activity is performed on systems that are poorly documented and were built without the benefit of modern design practices. When working on such systems it is often useful to record knowledge gained about the system from examination of the source code. This knowledge can then be used by other, perhaps less experienced programmers, working in the same area or by the original programmer when working in the same area at a later date. This paper discusses the importance of documentation in the maintenance phase and proposes a tool based on hypertext technology that can meet a number of the documentation needs of the maintenance programmer. The Software Maintenance ProblemThe phrase 'software maintenance' has been defined in varying ways by many people. Any disagreement usually occurs on the number of activities that the term encompasses. I shall use a broad definition given by Foster [5].Software maintenance is the set of activities associated with keeping operational software in tune with the requirements of its users and operators, and of all other people and systems with which the operational system interacts.Within the software industry an awareness of the significance of software maintenance as an activity that deserves specific attention is growing. This awareness can be attributed to a small group of academic and industrial guru's who over the %ponsored by British Telecom Research Laboratories for a one year Research MSc in Software Redocumentation at the University of Durham.

Using literate programming to teach good programming practices

“…A survey by Chapin [4] of maintainers showed that they pereeived poor documentation as the biggest problem in software maintenance work. Poor documentation has one or more of the following characteristics [9,4,8] There arc a number of CASE tools available that claim to satiso the documentation needs of sotlware maintensnec, These tools generate automatic documentation in the form of reports by static analysis of source code.…”

VIFOR 2: a tool for browsing and documentation

“…Hypertext is a powerful tool for software documentation [5,8,9,10,11], and has b een used for annotations of code. The annotations are explanations of various constructs of the code.…”

A combined representation for the maintenance of C programs

“…The strategies outlined in this paper are very similar to those employed in maintenance environments such as those described by Cleveland [19] and Fletton and Munro [27]. Hypertext systems…”

“…The concepts introduced by Foster and Munro [31] are expanded further by Fletton [26] and Fletton and Munro [27] to give a hypertext tool linking cross references, source code and documentation.…”

“…The views presented are limited to those only provided by static analysis tools and the resulting environment is very similar to that described by Fletton [26] and Fletton and Munro [27].…”