October 2005

Single Point Requirements

The "Simple Case of A500" occurred 10 years ago. I'm currently coding the "Son of A500". Completely different companies, completely different products, a decade apart. I'm the only common factor. And even I'm different.

The Simple Case of A500 started with a request to automate a recipe generating function. For an example, the customer provided a copy of one recipe, you guessed it, A500. Bravely we marched off, returning a month later with the ability to automatically generate the recipe for A500!

Making a long story short, it turned out that A500 represented the simpler recipes in the class, and for extra enjoyment, the example they provided was the simplest of the simple. It took another 2 months (which means the project took 3 times longer than planned) to finally get the client what they REALLY wanted.

The take home lesson we learned, "Don't accept a single example for requirements that cover a class." We even referred to ensuing similar requests (from them and other clients) as "Oh yeah, it's the simple case of A500."

Ten years later, I'm still getting requests for "Don, do this, and here's an example." The current case started as "We need to be able to detect faulty thermocouples." and a dataset that showed one of three thermocouples not working correctly.

Being older and wiser, I'm now working with the clients helping them understand that, "Yes, we can handle the request, but with a single example, I can't ensure that we'll handle a significant portion of the class, much less all the possible permutations that could arise." It usually takes a lot more words, but so far I've been successful helping the clients understand the need for better requirements definition and examples.

Got an example of "The simple case of A500"? Send me an email to don@donaldegray.com

Different but Useful

"A map is not the territory it represents, but if correct, it has a similar structure to the territory, which accounts for its usefulness." - Alfred Korzybski

Recently I spent two weeks in Berkeley CA helping a client upgrade one of their control systems. I wasn't involved in creating the original system, but I do have experience with the software. We reverse engineered and re-created the system. Testing went well until the fateful day we hit the wall.

The task is simple enough. The operator makes a selection, which sets a boolean value TRUE. The control computer detects the FALSE-to-TRUE transition, and sets a local variable to TRUE. Six seconds later, the operator's value gets set to FALSE. The value in the control computer remains TRUE until other events occur that set the variable to FALSE.

This was the map I used until things didn't work. The communication between the two computers wasn't happening like it did with the original system. The original communication protocol worked synchronously. The new communication protocol works asynchronously. This didn't matter for most actions, but did create problems with this particular code section. And while we could bend, fold, and mutilate everything on the operator's computer, we couldn't make any changes on the control computer. To make matters more interesting, the interface logic occasionally worked. So my map was sometimes correct, and sometimes wrong!

After a day of testing, re-coding, and testing again, we finally resolved the issue so the interface reliably worked. The actual code changes were simple. We spent the majority of the day deciding if the map was correct and the territory wrong, or the territory was correct and the map needed changing.

Maps make it easier for us to work with the real world (whatever that may be). Some detailed information gets removed, but if the structure is similar to the territory, the map is useful. The problem is deciding when and how to change maps.