Helping Maintainers

There are two broad categories of documentation which exist and are or can be maintained outside the code. 

         These can broadly be defined as User Help/Specifications and Design/Architectural Descriptions. This blog posting is about Design/Architectural Descriptions.  A previous posting covered User Help/Specifications.

         This type of documentation is intended for use by maintainers and to a lesser extent by project stake holders.  From a maintainers perspective, this type of documentation is useful only if it leads to a quicker (than just reading the code) understanding of what the major software and hardware elements are and how they relate to one another.

         The characteristics of  software architecture documents are:

1. Highest level of abstraction
2. Focuses on the components needed to meet requirements
3. Describes the framework/environment for design elements
4. No implementation information

         The characteristics of software design documents are:

1. Lowest level of abstraction
2. Focuses on the functionality needed to meet requirements
3. May only hint about implementation

As appropriate it should have diagrams and/or descriptions of the major modules and how they relate to each other both structurally and at run time ( data and/or control flow relationships ).
       
          For large and structurally complex applications which have been written in an object oriented language, there are tools which will generate UML class diagrams of the modules similar to the following.


For maintenance purposes on large/complex systems I have found these diagrams to be useful only as a starting point for checking references to a method as part of a proposed defect fix.  I say starting point because it mainly serves as a way to estimate potential effort.  More times than I care to think about, I have written a Perl script to scan all files in a project for a given symbol or set of symbols.  The Linux grep command can be used to do much the same thing.  Both of these scans can also check external documentation files. The virtue of the Perl script is that it can be easily modified to make the desired change to the code and comments.

I am not saying that auto generated UML diagrams are useless, only that they should not be the only external documentation for a project intended for maintainers.  Consider who the maintainers might be.  It may be that not all maintainers under stand UML diagrams.  It is possible that some maintainers will have expert specific domain knowledge but not much software expertise.

Consider management type people .....

•