Make your own free website on

“Why” Diagrams

Author: Vladimir Mikhalyev


If we analyze most of the documents, used in software development, they are mainly about two basic questions: what and how. What should be done (requirements) and how is should be done (design documents). Sometimes it is not easy to tell the difference, because low-level design documents in fact describe how to implement what is described in higher-level documents. So from this perspective they are all about what and how.

As a result most of UML diagrams are mainly to visualize answers on these questions. After a long way from initial requirements to finial implementation there could be hundred of documents and diagrams covering everything from the first idea on architectural level to the programmers’ tricks in small subroutines. But it seems that one basic question is almost forgotten in the documents and diagrams: why. People ask this question all the time, but usually they write down in document only final solution, sometimes forgetting about reasons why the decision had been made, and almost always ignoring alternative ways and explanations why they were rejected. Meanwhile everybody witnessed a lot of developers with frustrated faces and pathetic questions like these:

-         Why did we do this way?

-         Why didn’t we do it that way?


“Why” diagrams are designed to answer these questions, to visualize not only solutions, but also the ways to the solutions, including rejected ones.


To introduce “why” diagrams let’s look at the following sample of a discussion about client side of a Web based application. If you don’t familiar with the issue don’t worry: we are not going to analyze it from technical point of view.



-         We are going to use Web pages with DHTML to implement our front end. Now everybody has Web browsers, so our clients need nothing to download or install.

-         But that means we can’t provide really rich GUI, because HTML has very restricted set of input controls. Sure, we can use DHTML to emulate some controls, like pull-down menus, tab-controls and even rich-edit multi-line text boxes. But these controls, which are very simple in regular applications, become pretty complicated in DHTML. And what are you afraid of? Downloading isn’t so bad idea now. More and more people get fast Internet, so they can download 10 MB in minutes.

-         So what is your solution?

-         Well, I like browsers, but I would implement all GUI as a Java applet. Now, using Java Swing, we have everything to create really friendly GUI. And applets are pretty small. So it is not a big deal to download them.

-         Have you said Java Swing? Bad news for you. It requires Java 2 and currently Internet Explorer doesn’t support this JVM.

-         Yes. But users can download this JVM for free, plus a little component to run applets as ActiveX controls.

-         Aha. That means several mega bytes to download at installation time. You can forget about users with dial-ups.

-         Well, it is another reason for them to get fast Internet. Who knows how many of dial-up users survive in a couple of years?

-         For that matter, who knows, what kind of rich GUI will be supported by Internet Explorer and HTML in 2 years.

-         You know, I agree. And may be it will go with Java 2, so there will be no need to download JVM.

-         If you like so much to download everything, then how about this: DHTML pages, plus ActiveX controls in places, where we want to provide a complicated GUI. Market is full of 3rd party ActiveX components with any kind of GUI you can imagine.

-         Are they free?

-         Most of them. Any way they are not expensive. After all we can develop them ourselves.



The discussion could be continued to the end of times, covering such issues as development efforts, security, increasing (or decreasing) monopoly of Internet Explorer and Windows, etc. Let’s just look at this small part of the problem, covered above.

Also we are not going to analyze this discussion from professional point of view. All we want is to parse and visualize the discussion, including possibly wrong or rejected branches.

We see two possible solutions: Web pages with DHTML and applets. The following targets were discussed: convenient user interface, easy installation and client expenses.

Client Front End

The “ActiveX” box represents a small sub-diagram.

ActiveX Box


The following symbols were used.

Fork. Selection between two or more options.

X leads to Y

X increases Y. Minus would mean – decreases.

Z increases influence (positive in this case) of X on Y. Minus would mean – decreases.

X and Y together lead to Z.

Both X and Y increase Z, but Y is more effective.

Fact, unstable in time. Something, which is true or important now, but can become false or ignorable in future.

X is itself an another diagram and depending on option, selected inside X, it may or may not lead to Y.



We see that both options are not ideal. Regardless of final decision it would be a compromise, e.g. between product cost and user interface convenience. Also the correctness of the decision would depend on future, which is not easy to predict. In 10 years there will be a completely different situation on software market. If the same people start this discussion again it would go in a quite different direction. But having the diagrams above they can easily restore the original discussion and its logic. Also a newcomer can look at the diagram and understand what was discussed long ago, why a solution had been made and other ways were rejected.

Personalized Diagrams

Sometimes it important to remember not only why a decision was made, but also who made it, who opposed it, who gave the original idea of the solution, etc. So it seems to be a good idea to add this optional information to the “why” diagrams. Let’s look at new version of
ActiveX sub-diagram, which now includes the personal information.

ActiveX Box (personalized)

In fact the added boxes can have any text: objections, doubts, comments. They must have the person name. Also, if the discussion was long or the comment was added later, they should have dates and may be times.

Interactive diagrams

It would be great to have an application, which helps to draw the diagrams. In fact, if we want just to draw and print them, there are many available applications like MS Visio, which can draw almost anything.

But the diagrams could be much more helpful, if they are interactive. Let’s look at one simple example. In the first diagram the influence of  “ActiveX” box is controversial. If we can select the box and see how it affects other parts of the diagram, we could see something like this.

Influence of ActiveX

The following colors can be used to show the influence.

-         Green – the factor was improved or increased.

-         Red – the factor was damaged or decreased (not used in the example above).

-         Yellow – the influence of the factor isn’t easily predictable.


Even without a special application for the interaction, it is possible to draw and print the diagrams showing influence of different factors. But, sure, for really complicated diagrams it is cumbersome to create its versions for all possible influences.

Universal Use

At closer look the “why” diagrams have nothing common with software development. They can be used at virtually any branch of human activity, where it is possible to ask “why” questions. Let’s look at the following diagram about one of the everyday problems: a place for a party.

Place for Party



“Why” diagrams are not a remedy. They cannot generate ideas and make solutions. But they can help to create conditions, when it is easier to generate ideas and make solutions. Also they save the process of problem solving in a simple and catchy way.