One of the eternal challenges about designing a bespoke system seems to be making sure that it is supportable in the future by getting all the information about it available to Those Who Need To Know. Furthermore the range of information is very broad, ranging from descriptions of the business purpose of functionality to descriptions of individual objects and their attributes. Consequently is is often very difficult to hit upon the most appropriate for of documentation.
For example, if I have a data warehouse fact table for which there is a single foreign key column that is nullable then some documentation is called for. When you describe that table through SQL*Plus that nullability really leaps out at you — how do you document the reason for this design decision? Maybe through a comment on the column, stored in the Oracle data dictionary, but how many people ever look at that kind of thing? Some people aren’t even aware that such a feature exists. How about a document in a shared folder? Maybe, but people are always tempted to print it out and put it on a shelf somewhere, and it’s always tricky to arrange formatting and organisation of such a thing.
Another example: “This table has multiple materialized views defined as ON COMMIT REFRESH COMPLETE so a commit will appear to take a longer time than usual”.
It seems to me that what is needed is a general repository of information for an application that is easy to update and easy to view, to allow comments to be stored againt tables, indexes, column, triggers, packages and whatnot. The feature of being easy to update is to me critical. If it is going to take someone more than a couple of minutes to write a note then realistically they are not going to make much effort to do so.
So anyway, it seems to me that a Wiki would be just the thing for this — easy to search, easy to modify, easy to link from one article to another. Thus I can have an entry for my fact table, say “FCT_SALES” that either links on to columns or has a subheading that allows me to annotate the information that column “SALES_ACCT_CD” is obsolete and all values are null from 2003-01-01 onwards, for example.
It also seems that it would be handy to be able to add in more generic subjects, such as on table compression and the problems in trying to update compressed data, with links to online Oracle documentation as well where appropriate. In other words, notifying support persons about the major issues associated with the use of particular features and providing links for further reading.
Wiki’s are not exactly at the cutting edge of technology anymore, and their very purpose is to collect and catalogue a wide range of unstructured data. They seem like just the thing.
Another thought: I do not understand why companies are so enamoured of support solutions that lock away problems in a database somewhere with a client-server style front end. Is it beyond the wit of man to use in the technical support field what we so often use in the real world — a forum approach? Again, it’s easy to update, easy to search, and open to all. Maybe back the whole thing up with more formal bug tracking and problem logging software for the usual password change requests and formallly identified issues, but there seem to be so many questions on the use of an application that a forum would be an ideal mechanism for sharing the knowledge.
Now all I need is someone willing to try out the ideas, or report on their own experiences with such methods.