June 14, 2006

2-Way Documentation

I've noticed a pattern. Some PeopleSoft installations have no custom documentation whatsoever—but I'm not really talking about that situation today. Others have voluminous documentation best measured by the pound. This may include functional and/or technical documentation describing the final customized system. But it seems that in many cases, there is little or no documentation within the code and objects themselves. The objects are simply created or modified, with no comments attached. This makes it difficult to track a change back to the reason it exists.

Documentation should go both ways. There should be documents describing the changes we are making to the system, but there should also be documentation within the system itself pointing back to the requirements that triggered the changes in the first place.

When we are investigating issues and encounter a custom or customized object, it is almost always helpful to be able to track back to the original requirement. Most PeopleSoft object types provide a place (under "Properties") to enter comments. Object such as SQR programs, of course, should also contain comments. However, I believe that each line should be tagged. (It's not as much work as it sounds.) The best way to provide this information is to tie everything—the original documentation, the object comments boxes, and the program lines—to an issue or incident tracking number. Text comments are useful, but the tracking number gives us access to all of the relevant information about the change.

In the absence of these comments, it is sometimes possible to track back to the other documentation and other objects using either the Application Designer project, a Stat CSR or some similar packaging mechanism. But overlaps in projects can make this difficult. There really is no substitute for good, traceable links from requirements to customized objects and back.

Until next time...