Experience with the Use of Precise Documentation

Mr. Brian Bauer
(bbauer@newbridge.com)

Dr. David Lorge Parnas
(parnas@mcmaster.ca)

Software Engineering Research Group
CRL, McMaster University,
Hamilton, Ontario, Canada L8S 4K1


Abstract

A student with no previous exposure to mathematical software documentation techniques was asked to document a program that had been written by a programmer who had left our laboratory. The program was needed for communications research but it did not work as expected and nobody was able to determine why. Although this student was not asked to change the program, just to complete the documentation, the process of documentation revealed several problems in the program and left it in working, and maintainable, condition.