Opinion: Five Diagrams Beat a 'Victorian Novel' Text Specification

Computerworld - Consider two methods of collecting and presenting computer system specifications to users. One is far more likely to result in disastrous development projects plagued by miscommunication and users who are unhappy with the systems that are delivered to them.

This method uses Unified Modeling Language (UML), a variation on what used to be called “Victorian novel” text specifications. UML specs mire readers in a swamp of boring words. They rely on use cases that seem very rigorous yet manage to reduce everything — from trivial details to important processing logic — into a monotonous blur of text that few people can read for more than a minute or two.

> The only diversions from this text are some abstract charts, but they too are filled with words. UML documents seem to be purposely designed to confuse and disengage the typical business user. The method’s widespread use is hard to explain, since it can probably be blamed for many failed system- development projects.

> Instead, I use a method based on the old saying that a picture is worth a thousand words. I use schematics and diagrams that give both business users and developers an easy way to understand the system under development. I have seen again and again that just five diagrams can capture all necessary system design specifications. More important, these five diagrams enable effective communication between business and technical people so the system that gets delivered meets user expectations. Let me describe each diagram.

> The first is a process flow diagram. Sets of leveled data-flow diagrams usually work best because they are easy for business people to understand. At times, flow charts and swim lane diagrams also have their place. People can quickly scan them and check for accuracy.

Fig. 1 Process Map 1

(Click here to see larger view.)

Fig. 2 Process Map 2

(Click here to see larger view.)

Fig. 3 Process Map 3

(Click here to see larger view.)

Next, I capture the data identified in the process flow diagrams and plug it into a logical data model. Business users see the structure of their data and can visually scan it to check for accuracy.

Fig. 4 Logical Data Model

(Click here to see larger view.)

> I then create a screen map and screen layouts. This storyboard of screens shows users how they will interact with the system as they handle the data in the data model and perform the work specified in the process flows. This is always the most interesting diagram to users, who can clearly see how the system is being designed to work. It’s where they provide most of their input.