Malcolm Cowen on documenting the orphan system at Woolworth's

A problem frequently encountered is the so-called “orphan system”, when you lose track of the sources or the documentation for the system. Perhaps you can’t find them, more likely you can find several versions, but you don’t know which is the real one.

Documenting “Orphan Systems” - Malcolm Cowen

A problem frequently encountered is the so-called “orphan system”, when you lose track of the sources or the documentation for the system. Perhaps you can’t find them, more likely you can find several versions, but you don’t know which is the real one.

Of course it’s a situation which should never happen, but sooner or later it does. And when it does you are seriously at risk.

During my career in IT I have had to clean up several such disasters:

· There was the case of the software support man who disappeared in dubious circumstances, taking all the support knowledge with him, and what's worse the master password as well.

· There was the end of project party where someone put the only copy of the documentation down somewhere, and forgot just where.

· There was even the "Programmer from Hell" who thought documentation was for wimps, and if it was hard to write it should be hard to maintain.

This article describes the most recent case that Malcolm dealt with, at Woolworth’s in Rochdale during the period Dec 1998 to Jan 2000. Woolworth’s have a large datawarehouse based on a Tandem system. It was designed for them on a tight timescale by an outside agency, documentation was not produced for the system, nor were the program sources held in any one place.

Malcolm was initially engaged to provide support for the system. Proper documentation was identified as a prerequisite for this task, and an ongoing activity was set in place to create this.

The critical criteria were as follows:

· The primary need was to provide an acceptable level of service to the users, this frequently involved operational compromises and assessments of urgency.

· Program sources were typically held in several locations. This required early resolution, as fixes could not be applied with any certainty to programs where the source was not known.

· An unknown number of programs contained calls to user written library procedures, which themselves had changed. Recompilations of these programs could therefore produce unexpected changes in program behaviour.

· The operational dependencies of the programs were known however it was not known which program modified which data table, furthermore it was known that some paths within the system were redundant and others were vulnerable to changes in the normal run sequence.

· The operation of the system macros to control such activities as compilation, testing, normal batch running and manual rerunning of failed processes was unknown. These control macros were run by rote using unwritten knowledge of what “usually” worked.

· Many of the system components, such as tables, were referred to by several different names in different parts of the system. Some components were redundant. There was however no cross-reference list of the various names, nor any description of their purpose.

The policy Malcolm adopted was that subject to the overriding needs of the support function he would:

1. Back up the entire system as it stood, to provide a fallback in the worst case to a known working system.

2. Establish a documentation skeleton into which documentation could be placed as it was written or found. Layout standards were also established, however the decision was taken that font and style consistency would be regarded as secondary to content, at least until there was time to apply such standards.

3. Attempt to resolve as many uncertainties of sources and multiple names as possible using automatic means, and to flag the cases where there was known to be uncertainty. This resolved about 80% of all cases, which could then be handled with more confidence, thus speeding up the support function.

4. Set up release control procedures, obtaining the approval of the project manager and all other staff for their use. This at least stabilised the system, and meant that support work in any area would henceforth tend to slowly extend the known and documented areas of the system.

5. Collate any paperwork he could find and include it within the system, together with an assessment of its trustworthiness.

6. As particular mechanisms within the system had to be investigated for support purposes, Malcolm ensured that knowledge thus gained was documented and included in the documentation.

7. Files which appeared not to be accessed were noted and eventually all such sources and other files were renamed and then later deleted from the live system.

The documentation produced was about 80% complete after about three months, and better than 95% complete by the time of Malcolm’s departure from the project after 14 months.

As a result of this work the response time of the support team, and the number of serious system outages declined significantly. Additionally as understanding of the system grew it became possible to apply improvements with more confidence and the run time of the system significantly improved.

(Malcolm Cowen is a director of Cowen Software Ltd. He can be contacted at malcolm@cowensw.com)