March 14, 2007

The Data Doesn't Lie

I've stolen the title of this post from a contractor friend. "As I always say, the data doesn't lie," he said the other day as we were chatting about problem solving or something. I completely agree. Now, if I've ever had a thought along similar lines, it would have to be "the code doesn't lie."

What are we talking about here? Well, think about the times you've been thrown into a new situation without the necessary background or preparation. Maybe it's a new employer or client. Maybe it's a module you haven't supported before, or just a strange bug. Or it could be a user's question such as "What does the system do in this case?" Assuming here that you have some background (because it's a PeopleSoft installation, for example), where do you start?

Many people would open up the documentation and start reading. There are many places to look. You could start with PeopleBooks. If there is any customization, you could read the requirements document, the technical specs, or any of the many other pieces of up-to-date documentation you have on file. (Stay with me here.) Or you could call on the expertise of other people.

Very often I tend to prefer a different route, and I think my friend takes a similar approach. I like to look at the code and the data. You can learn a lot from reviewing the structure of the data (App Designer being a good place to go for this) and the actual values stored in the tables. Focus especially on the keys. They can tell you so much about the purpose of a table, the type of data it is intended to contain, and its relationship to other tables. PeopleSoft database tables generally contain consistent field names, and so that gives another clue.

The characteristics of a field can also convey good information. Suppose that you have a field in your HRMS/HCM system called MANAGER and someone asks you what it's for. You might not be sure. Now look at the definition of the field in App Designer. What if it's a 1-character field? 11 characters? 30 characters? Each of those possibilites gives a very strong indication of the purpose of the field.

Even if a field name is used in an unusual or misleading way, the actual data doesn't lie. The fact that most PeopleSoft tables (or at least the delivered ones) are fairly well normalized also helps in understanding. I very often find myself going directly to Query Analyzer or Toad or whatever SQL query tool is available. In many cases, that's as far as I need to go—even with the voluminous and highly accurate documentation that is always available (hey, you have heard of "suspension of disbelief," right?).

It's similar with code. When asked "What does this program do?," I have the choice of finding the documentation, reading the comments, reading the code, trying the program, and/or asking someone. If the question is of a very general nature, asking or reading the documentation is generally sufficient. But if it's a detailed or technical question, I tend to go right to the code. It may be a bowl of spaghetti, but it doesn't lie. Even comments within the program itself can be important clues, but...well, we must comment our code, of course, but I'll leave it at that. You have seen questionable examples just as I have.

Note the important distinction between "What does this program do / What does this table contain?" and "What should this program do / What should this table contain?" For the "should" questions, it's very useful to have the original intent written down somewhere. The data and code don't lie about the current state of affairs, but in some cases they are completely ignorant of what they were supposed to be doing in the first place. Contradicting everything you have heard about what documentation should contain, I'll just propose that the original motivation for the system or customization—the statement of the problem to be solved and the general way in which it was to be solved—is the most useful. Detailed documentation of what was (supposedly) done and how it was (supposedly) done is much less useful. Because, you know, the code and data are there in plain sight, and they don't lie. If you are filing program listings, field attributes, SQL statements and such in big binders, it will be quite impressive. But are those binders maybe just a little dusty?

Until next time...