Documenting Retired Customization | KEVIN RESCHENBERG 03-28-2004 |
The client was using Quest's Stat product and asked me how best to document customizations that are being removed or retired. This turned out to
be a difficult question. It wasn't just a question of how to use Stat to accomplish this (how do we reopen a ticket that was closed months or
years ago?); the larger question is how to track the loss of customization at all.
Most installations keep some sort of documentation of customizations. It might be stored within an incident tracking system or separately.
Now, suppose that a simple customization—say, one block of PeopleCode—is no longer needed and the client decides to remove it. In that case
we simply go to our documentation and either make a notation that the change is no longer in effect or delete the original documentation.
But few things are ever that simple. Suppose the customization involved many PeopleCode programs and other objects. Over time, some of these
changes will be overwritten by delivered patches or upgrades. If the delivered functionality duplicates the original customization, users will
never notice the shift and our documentation is still accurate, even though it's no longer talking about customization.
Another case involves complex customizations that are overwritten by other changes, some related and some not. Over the years, a project that
initially covered many records, pages, programs and other objects can tend to "fade away" as bits and pieces of it are overwritten, enhanced, or
removed. Will the original documentation be updated with each change? It should, although you can see that there are situations in which we
may not make the connection. Over time the customization my morph into something completely different or disappear altogether, but some or all
of the documentation may remain.
This leads into the question of the purpose of documentation in general. I'll deal with that topic in the future, but today I'll just end by
saying that I rarely rely on documentation to tell me what the system does. Documentation—specifically, good documentation—is more
useful in telling us why and how the system does what it does. Now, I'm certainly not saying we don't need good documentation,
or that we shouldn't document what the system does. This can be very useful for many purposes and for various audiences. I'm just saying that
it can be dangerous to rely on it. When a user asks me specifically what the system does in
a particular situation, I go to the code—or just run an example to test it out.
|