Documentation following the rules: the Case of the Laboratory Applications

A specialist scientific company had over the years produced many applications to assist with laboratory work. Some were simple calculation routines, and others controlled various pieces of laboratory equipment. None of them had accompanying documentation. Management was getting concerned about the long-term maintainability. Also, there had been critical comments from their accreditation body: for them the software was a black box, whose correct operation had to be taken on faith.

What We Did

The end result was a set of documentation products that all used roughly the same format. From these documents a third party can understand what each application does, and a maintenance programmer can understand how each application performs its job. Until the documentation process was started, no-one other than the programmers had ever seen the code. The process therefore revealed many opportunities for improvement: routines that were not actually used, routines that were identical (or nearly identical) to other routines, and duplicate classes. All these were reported to the client and marked in the documentation.

How We Did It

We developed a template based on IEEE Std 1016-1998 (see Notes). Each application was then described and fitted into the template. At the same time, any areas that could give rise to problems during use were flagged. We also described all the equations and formulas used, where possible including references to publications providing the theoretical basis for them.

As not even an initial requirement document was available, much less a software design description, most of the work was done from reading the source code. Dividing the total number of lines of code by the time required, shows that we documented, approximately, 800 lines of code per day.