When the revolution comes.... (management information systems)

The Information Systems department announced that it was embracing the object-oriented paradigm for its application systems development and reengineering efforts. I had spent a large amount of money for new object-oriented development tools and would be training all of its staff in the new methodology. I smiled... in amusement. I am a former `team member' of this particular department, and I knew this was the latest revolution being waged to solve the twin problems of increasing development and maintenance backlogs and decreasing customer satisfaction. A revolution led by rebels without a clue.

While the IS management rebels are pressing their full scale frontal assault with their development tools and methods, the real enemy continues unchecked to plunder scarce resources. The real enemy is the sloppy practices of the department, and one of the worse results of these practices is the lack of application systems documentation. I remember many times asking for documentation on a file and receiving as a reply a copy of the source code of a program that updates the file. I can also recall innumerable times when I spent two weeks reverse engineering a system so I could make a change. The change took me two hours to complete once I determined where it needed to be made. This is not an embellishment, this is a fact I determined by examining my old time log sheets. In this and many other cases, a development tool that increased my programming productivity one hundred percent would only save me an hour... and do nothing about the two weeks I lost.

So why is the state of application systems documentation so bad? The first people to be blamed are the programmers. However, blaming the programmers is wrong. Contrary to the belief of many IS managers, programmers want to create documentation. The problem is they do not know how, nor are they given the resources to do the job. Unless they are trained to do otherwise, most programmers will write about the technical details of the programs in their documentation. This is better than no documentation at all, but not much. Programmers need to be taught that program documentation should not report, for example, that the customer file is open for input, a fact that can be ...