n an ideal world, all software and database systems would have clear documentation that is always up to date. In the real world, however, documentation usually is either non-existent or so out of date that it is misleading. This is especially true for legacy software systems that were developed before the industry realized that maintenance is the most costly aspect of a software system.
One of the main causes of incomplete or out-of-date documentation is the lack of simple tools and processes for integrating documentation into the design process. The simplest way to overcome this issue is to get developers used to writing at least as muchand possibly morein-line comments as they do code. For database systems, the use of internal comments is an effective way of ensuring that at least some documentation is written.
The Case for Integrated Documentation
Keeping the documentation within the system (a.k.a. integrated documentation) has many advantages. The first and most obvious advantage is that integrated documentation will never be lost. You may ask how would documentation get lost in the first place. Well, when a system has been around for decades and the people who wrote it are gone, its documentation likely will end up missing or misplaced. And even when found, it usually is so dangerously out of date that most developers are scared to touch the system with a ten-foot pole.
The second advantage of integrated documentation is easy to start and maintainso much so that there really is no excuse for not doing it. Every time you change something in your code or in your database, spend a few minutes to also update the comments. It is as simple as that.
The third advantage is integrated documentation makes it very easy to divide software or database systems up among developers at different sites, and merging the documentation requires little effort. When you merge the software/database, the documentation is merged for you!
Recognizing these benefits and the urgent need for them, we developed an in-house, integrated-documentation tool to help document both legacy systems and systems inherited through acquisition. As its GUI, the tool offered a PL/SQL-generated HTML database dictionary. The tool became very useful when dealing with offshore development teams as well, when many groups were working on different parts of the system. More recently, it has become popular with data-mining folks, as each new project presents them with a new unknown database. This article explains how our tool can help you create and maintain documentation for Oracle databases.