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.

Top down explanations

I just sat through a lengthy presentation where someone attempted to describe a software product to an audience (including me) unfamiliar with the product.

He started his presentation by showing a pie divided into about 12 different pieces. Each piece of the pie was a software module that performed some function of the overall product. He then described, in detail, the functionality of each pie piece. This took 90 minutes - about 89 minutes too long. After that he gave a demo of the product.

It was agony.