Event based explanations

Explaining the different components or modules in a software system can be difficult. It is similar to explaining all the different components that make up a car (the ignition system, the brake system, transmission, etc.) and how they work together to get a person from point A to point B. A well designed software system usually has several modules, each with a specific role. Trying to describe how these different modules work together, though, can be a challenge.

I discovered this the first time I had to hand over a system, that I had developed, to another person. Amy is one of the smartest people I have ever worked with. Although she did not have much development experience, I was confident she would have no problem understanding the system.

The system was a tracking system used to track products as they were being repaired in the company's warranty and support center. Bar code scanners updated a database with the location of the product as it moved through the repair process. The system would import data from other databases every night into the system's database. Reports were provided to the supervisors so they could schedule work and people. It wasn't very complicated - at least I didn't think it was.

I was moving on to a new job and Amy was going to take over support and development of the system. A week was the amount of time I was given to train her on the system. This should be more than enough time, I thought.

On the first day I started by explaining how I had designed the database. I immediately started by opening the database and showing her the tables and their relationships. My ego could barely wait for her recognition that it was the most impressive thing she had ever seen. I had been talking for about 20 minutes - not even stopping to see if I was making any sense to her - when I asked Amy if she had any questions. She said very nicely "Ummm....maybe we should try a different approach. What happens when the operator scans the product in the shop?".

I couldn't believe it. She didn't understand anything I had just said. I was confused. Amy is extremely bright but she was having trouble understanding the design. It couldn't be my poor explanation, could it? Nah....had to be Amy.

So I proceeded to explain what happened when the operator scanned a bar code in the shop. I explained how the bar code scanner converted the bar code serial number on the product to a text-based version of the serial number. I then showed how that text made its way into the system and updated a table in the database. Amy grasped all of this immediately. She then asked what happens when a supervisor runs a report. I showed her the database tables the system uses to pull data from and how it summarizes it in the report. She was now starting to understand the layout of the database tables. This seemed to be working.....hmm....maybe Amy's brain is just wired differently than other people's.

We proceeded along this fashion for the next couple of days. Each step started with Amy asking "What happens when....". I would then explain all the components in the system that were involved when something was clicked, scanned, e-mailed, etc.. I started to realize how this method of explaining seemed to work much better than trying to explain the individual components of the system in isolation.

This lead me to think about how I would explain the workings of a car to someone who has driven a car but never bothered to understand how it works. Instead of opening the hood and describing each component, I think I would start with "When you turn the key the battery provides energy to the starter. The starter then begins cranking the engine....". I would proceed with "When you shift the lever from Park to Drive, the transmission ....". The person may have questions about the different components as I refer to them. I would provide explanations about those components when we encountered them.

This method of explaining a system by describing how different events flow through the system has proved very valuable to me. I was a member of a software team for a very large software system. There were over 50 different modules in the system. I knew how the higher level components of the system interacted. When introducing new developers to the system I found it was much easier to explain by starting with "When a user presses....", "When a user turns this knob...." and continuing in this fashion. I could cover most of the components of the system in a much shorter time and the new developers seemed to truly understand how the different components of the system worked together.