The final pragmatic guideline is to avoid analysis paralysis. If every picture must tell a story, then no picture should be drawn unless it tells a story. Track only the scale and amount of information you need to answer questions. A good design principle, whether for UML or not, is design what you need, and then shut up! Don’t draw diagrams that don’t reveal more about the system than you already know. Eliminate truly trivial diagrams. The principle here is just enough modeling: just enough to answer questions, discover new questions, and answer those, but not to create every diagram you possibly could. That’s too much.

Is it possible to overlook a valuable diagram this way? Of course. But with a good review process, you’ll catch these, when reviewers scratch their heads and look at you funny. They’ll tell you that you’ve missed something, and you’ll insist that it’s trivial. Fine. Prove that it’s trivial; but prove it by drawing the trivial diagram. Either you’re right, and you’ll prove it trivial through use of the new diagram; or you’re wrong, and the new diagram will reveal why. In either case, your communication will improve. But in no case do you say, “It’s obvious! You just don’t get it!”

This rule does not apply, of course, if you’re on a MILSPEC or mission-critical system that demands much more extensive documentation. You have to manage the artifacts of your process, not just the process itself. This rule encourages a focus on artifacts over process. Sometimes, however, the process demands certain artifacts. Part of the review process must include verifying that all legally mandated diagrams are produced.

How Much Can “Too Much” Be?

A student recently asked me, “How many diagrams could we draw, if we wanted to be thorough?” I’d never really thought about that problem before, because I always knew in my heart that the answer was “Too many.” But I realized that this could be a pretty useful question: if some manager did insist on every diagram as part of a “correct” process, how much effort would be involved? So we did some back-of-the-envelope calculations for a small system, based on all the different diagrams that I might draw under certain circumstances. These are necessarily very rough estimates, but they give a pretty good feel for how large such a “correct” process can be:

• Within the requirements model, assume a top-level “navigational” diagram. 1 diagram.

• Assume the system is designed for the requirements of approximately 10 different primary actors. That’s enough actors to make me expect that there are at least 2 actor packages—each with a diagram—and a package of actors with a diagram that shows the 2 packages. You’ll often find a “common” package of actors as well, with its own diagram. 4 diagrams.

• For a really thorough understanding of the problem domain and requirements, you might draw a domain Class Diagram for each actor, including all the other actors and all the domain objects with which it interacts. 10 diagrams.
  
• For each actor, you’ll produce a requirements Use Case Diagram that depicts the use cases required by that actor. 10 diagrams.

• For each actor, you might also want a requirements Use Case Diagram that depicts the domain objects modified or maintained by its use cases. 10 diagrams.

     • As a rough average, each actor will require approximately 5 use
       cases; and of those 5, roughly 2 will have complex relations to
       other use cases, which will require separate diagrams. As
       another rough average, these complex use cases will each be
       related to approximately 2 new use cases. 20 diagrams.

• For each actor, you’ll have roughly 3 simple requirements use cases, 2 complex use cases, and 2 related use cases for each complex use case, which gives you a total of 9 requirements use cases per actor. For each requirements use case, you’ll draw an Activity Diagram. 90 diagrams.

• Each requirements Activity Diagram will have roughly 7 activities (action states) in it; and of these, roughly 3 will be complex enough to be subactivity states, each with its own Activity Diagram within it. 270 diagrams.

• The activities within a subactivity state are usually simpler than the activities in a top-level diagram; but even so, some will have enough complexity to deserve to be subactivity states themselves. Assume this second set of Activity Diagrams have on average around 5 activities, and further assume that 1 out of 10 of these are complex enough to be subactivity states. 135 diagrams.
  
• As a rough average, assume each actor is involved with 2 unique domain classes. (Many actors will be involved with more than 2, but there will be some overlap.) This leads to 20 domain classes. That is enough for a domain objects package with approximately four subpackages, along with a diagram for each package. 5 diagrams.

• To really comprehend each domain class, you can produce a separate diagram to show the class and the classes that are immediately related to it. 20 diagrams.

• To really understand each domain class and how it changes in response to events, you can produce a Statechart Diagram for the class. 20 diagrams.

• As a rough average, assume each domain class Statechart Diagram consists of 5 states. Of those, roughly 2 may in fact be composite states, each with its own diagram. 40 diagrams.

• Within the architectural model, assume a top-level “navigational” diagram. 1 diagram.
  
• For each requirements Activity Diagram—including Activity Diagrams nested in subactivity states—you’ll draw an architecture Activity Diagram with swimlanes. 495 diagrams.

• Within the architectural model, assume a package for interfaces and a package for user interfaces, each with a detail diagram. 2 diagrams.

• As a rough average, assume that for every 10 architectural Activity Diagrams 1 new, unique swimlane is introduced. (Most Activity Diagrams will involve many swimlanes; but there will be lots of overlap, so assume 1 per 10.) This leads to 50 swimlanes, and thus 50 actors, interfaces, and user interfaces. Because you’re already assuming 10 actors, that leaves 40 interfaces and user interfaces. Those 40 can be grouped into roughly 8 packages, each with a diagram. 8 diagrams.

• For each interface or user interface, you can draw a protocol for its use, consisting of an average of possibly 2 Interaction Diagrams each. 80 diagrams.
  
• Within the architectural model, assume a package for the architectural view of components. This package should include both an Everything Diagram of the overall architecture, as well as a package diagram that shows the packages for the components within the architecture. 2 diagrams.
  
• Assume that, on average, each component provides 5 interfaces or user interfaces. That means that, for our 40 interfaces and user interfaces, you’ll need 8 components. For each of these components, you’ll make a new design model, including a top-level “navigational” diagram and a diagram that shows the component and those components immediately related to it. 16 diagrams.

• For each interface or user interface to a component, assume an average of 4 methods, each with 2 Activity Diagrams (with and without swimlanes). 80 diagrams.
  
• Within each component, assume an average of 10 classes. These are enough to justify 2 class packages per component (each with Class Diagrams) and a top-level class package with a diagram that shows the subpackages. 24 diagrams.

• You can understand each class more thoroughly by drawing a Class Diagram specific to it, showing it in the context of other classes. 80 diagrams.
  
• To really understand each class and how it changes in response to events, you can produce a Statechart Diagram for the class. 80 diagrams.

• As a rough average, assume each class Statechart Diagram consists of 5 states. Of those, roughly 2 may in fact be composite states, each with its own diagram. 160 diagrams.

• As an average, assume each class has 4 operations. For each operation, you can draw 2 Activity Diagrams: 1 with swimlanes and 1 without. 640 diagrams.
  
• The 8 components need to be deployed; so you need 1 logical Deployment Diagram and 1 physical Deployment Diagram. 2 diagrams.

• Assume an average of 4 nodes in the deployment. For context of each node, you’ll draw 1 logical Deployment Diagram and 1 physical Deployment Diagram. 8 diagrams.

So to analyze and design this fairly simple system—only 50 functions, really— you could potentially draw as many as 2,313 diagrams. Assuming that each diagram takes a half man-hour to create and another half man-hour to revise after review feedback, and that a team of four spends a half hour reviewing each diagram, then that’s a total of 6,939 man-hours spent on diagramming—or, even more frightening, three-and-a-half man-years.

It ain’t gonna happen. This project can’t justify that time expenditure. Only if it’s mission critical, only if lives depend on it, can you justify that much time spent on analysis and design for a system of that size.

So clearly, there’s such a thing as analysis paralysis, such a thing as too much modeling. And experience shows that there’s also such a thing as not enough modeling: not enough to really understand what you’re building. The trick, of course, is just enough modeling.

Next: Summary >>
 

More Practices Articles
More By Apress Publishing

Comments On: Pragmatic Guidelines: Diagrams That Work

>>> Be the FIRST to comment on this article!

Buy this book...

This article is excerpted from chapter three of the book UML Applied: A .NET Perspective, written by Martin L. Shoemaker (Apress, 2004; ISBN: 1590590872). Check it out at your favorite bookstore. Buy this book now.