Have you ever worked with, maintained, explored a system which looked and felt really great in one area, but was really awkward and clumsy in another one? That was an instance of an elephant on the crutches.

This often happens, when design specification was not consistent in the level of detail for different parts of the system. And here is how this may happen.

When you design a system, it is never going to be plain and the same wherever you look at. If you have a database and a user interface - those two parts are already different enough. Such diversity naturally leads to the fact that there are some parts that you enjoy working on more than others (after all we never like doing everything that we do).

What happens next is that you spend much more time thinking about parts you like (because there you use new fancy technology, or neat engineering approach, or who knows why). Therefore you add more details to design of those subsystems that you really like. The outcome of all of this typically would be a specification that is an elephant with crutches instead of hind legs, because elephant's butt was never you favorite part of the system and design of this "subsystem" never was detailed enough to make sure it is consistent with the front.

Ideally, your design should be like Google Maps: you should be able to zoom in and zoom out on any part you need. It does not make sense to have a map, which shows each and every tree in your neighborhood, but gives you only a vague idea about how to get to grocery store 5 miles away.

When developing and documenting design you should gradually and consistently increase level of detail in your specification. Ideally, difference in granularity of descriptions of different parts between any two parts of the system should never be more than one level. One possible way of zooming in would be to describe

• System + external interfaces, then
• Services and components, then
• Add their interfaces, then
• Add interaction (Sequence diagrams) and edge classes, then
• Components' structure and internal interactions, then
• Class-level specification for key requirements (functional and non-functional)

This is not the only possible way to zoom. However, when you have class diagram with methods and their parameters, but do not have stored procedures defined for your database, you are doing something wrong (or, hopefully, your design specification is not complete yet).

Design specification is only useful when it can help you answer questions you get during development. This essentially means that you should be able to navigate it and find things - which is zooming in and out and seeing enough to make the right turn.

Yesterday driving the city I noticed a big board which invited to buy a flat in a house. The interesting fact about this sell was that the is not built yet and the construction has not even started! But they have a fully visualized 3D-model of the house which you can use to imagine how your new dwelling will look like. I doubt that anyone has any apprehensions that real estate company can and will build the house so that it will look exactly like it looks in the model (i.e. in the project). So what they are essentially doing they are selling a design, not a completely usable product. Can you imagine anyone selling a design of a software product to end-users? Or even better, can you imagine anyone buying that?

Unfortunately, in software industry we do not get that level of credibility like they do in civil engineering industry. But I do believe it is possible with of software engineering profession. If you agree with me the Professional Software Development by Steve McConnell will reassure you. If you do not agree this book will, probably, persuade you that it is possible.