Pragmatic Guidelines: Diagrams That Work - The Résumé Rule (Page 4 of 8 )
There’s another problem with the Everything Diagram: either it’s too darn big, or the font is too darn tiny. You’ll be tempted to zoom out to fit everything, and then play games with the font to make it legible. But there are limits to that approach: when the font size is 1 point, it really doesn’t matter what the font face is; and if you enlarge the font disproportionately to the icons, the labels can obscure the icons. No one can review a diagram they can’t read. Amount of information communicated: zero.
So you’ll err in the other direction: larger diagrams at a scale you can read. Beware! That way, madness lies. You might split the diagram across many pages. Then you’ll ask me to review it. Unlike you, I don’t automatically recognize how the pages fit together. (Let’s be honest: you may not, either.) So I take it home to review. First, I have to clear off the kitchen counter so I have space to lay it all out. Then I have to throw the cat off the nice clear spot she’s just discovered. Then I have to try to lay out the pages. Then I have to throw the cat off again, because if there’s one thing she likes more than a clear counter, it’s whatever piece of paper is most important to me at the moment. Then I have to quiet the dog, who has decided that I need help disciplining the cat. Then I have to pick up the sheets that the cat knocked off the counter in her rush to escape the dog. Then I have to figure out if those marks are cat prints, dog slobber, or UML . . .
Plotter Horror
Or you’ll make the mistake I did: learning the arcane art of using the company plotter. Now I hope that plotters are better supported today than they were then; but in 1997, it took me and my boss all day to download the correct drivers and install them on my machine. (We installed a lot of incorrect ones along the way.) Now, truth to tell, I’m a night owl. We had that driver working at 5 p.m., just when my energies were really flowing; so the wasted day didn’t bother me. I proudly printed my first UML diagram to the plotter. Then, because of the physical layout of the company offices, I had to go up a flight of stairs, down a hill, around a corner, down another hill, around another corner, down another hill, across a busy street, around yet another corner, down yet another hill, through a security door, through a building I didn’t know, into the plotter room . . . only to discover that the diagram had printed incorrectly! So reverse the process (all uphill this way, of course), and repeat. By 11:00 p.m. (what a waste of prime programming time!), I finally had copies of all six diagrams I needed, one copy for each team member. I rolled them up, put them in tubes, and capped the ends. Then I carried all these tubes back up the hill, and put one in each team member’s cubicle, along with a handwritten note: “Hi! Martin here! These are the diagrams I promised you for review. I’d like to hold a review meeting Tuesday at 10:00 a.m. I look forward to your feedback. Thanks!” And then, Tuesday at 9:55 a.m., I heard pop! Pop-pop! Pop-pop-pop! All over cubeville, tubes were being uncapped for the very first time. Needless to say, that review was not very productive.
Your logistics may not be as bad as mine were. The plotter may be right next to your desk. But the result will be the same: your reviewers will glance at your work, compliment you on how much effort went into it, and never once review your design. Amount of information communicated: again, zero.
The best solution is the same rule the guidance counselors taught us all for résumés: one page. If a diagram can’t fit legibly on a single 8½×11" page, no one will review it. Although it’s true that such a page can get buried in an in-box, it also can easily be carried home in a briefcase, read on the airplane, and photocopied for more reviewers. The standard page size is overwhelmingly more convenient than is a great big plotter sheet or a diagram that must be laid out along an entire kitchen counter.
What if your diagram won’t fit legibly on a single 8½×11" page? Then, first of all, it’s likely that you have broken The 7 ± 2 Rule, but more significantly, you probably have too much detail at too many levels of scope. You can usually group many of the elements of such a diagram into fewer, larger elements, each with its own attached diagram on another page. Although it may seem to you like more work to add these additional elements and diagrams, that is from your perspective as the designer and originator of the idea. From an outside perspective, you’ll end up with a more comprehensible set of diagrams that convey your intent.
Sorry for My Cultural Centrism
Yes, I realize that in other parts of the world, 8½×11" is not the standard page size. Don’t take me too literally here. Use whatever is the standard page size for your locale. (Perhaps in those cultures, this should be called The Curriculum Vitae Rule.) But be hesitant of nonstandard sizes, even that of the infamous “yellow legal pad,” because they tend either to get lost in piles of larger paper, or they stick out of piles of smaller paper and get smudged, snagged, and ripped. Take a look at your last pointless memo from human resources, and use that size paper.
With both The 7 ± 2 Rule and The Résumé Rule, remember that you as the designer are not the best judge of what is comprehensible. First, as I discussed in Chapter 2, you’re weird: as a software developer, you’re better than the average reviewer when it comes to managing abstractions. So when you’re sharing your model with nondevelopers, they may be at a disadvantage. But even other developers won’t read your diagrams as readily as you will. When you read your diagram, you’re reading the real picture that’s already in your brain; but when reviewers read your diagram, they are reading the diagram and trying to understand what’s in your brain. Those reviewers need a lot more help than you do. And that leads us to . . .
“You Just Don’t Get It!” Is Never an Excuse As the designer and originator of the idea, it’s your responsibility to communicate it, and no one else’s. As long as the reviewer makes a reasonable effort to understand the idea, it’s up to you to make sure that effort pays off. The only measure of successful communication of an idea—in a slippery, circular sense— is when the idea is communicated back with no errors (and preferably in a different form). Until the reviewer understands the idea, you haven’t communicated. Keep trying.
But how do you keep trying? Try another approach:
- Add more detail to your diagram, to make a better picture of what you need.
- Remove detail as a way to reduce clutter. Every diagram need not display every detail. Remember The Model Rule: completeness lies in the model, not in any single diagram.
- Remove the detail—and maybe even some of the major elements— and place them in another diagram.
- Redraw the diagram. If you can’t get your point across, maybe a fresh start will inspire you to a better way of presenting the information.
- Ask reviewers to create a diagram of what they do understand. Perhaps when you see their interpretation, you’ll discover where the miscommunication lies, and you can correct it.
Don’t I ever get frustrated? Don’t I ever run into people—real, competent developers—who just don’t get it, just can’t see how superior and brilliant my idea is? Sometimes I think I do; and then I recall the words of Jim McCarthy:
The clearest sign that people are thinking is that they listen to other people’s ideas and critical feedback. They quiet their initially competitive responses to a possibly superior line of thought. They demand of themselves the intellectual rigor it takes to fairly and properly evaluate the new, potentially valuable information. They can filter out the ego-driven aspects of the communication they’ve just received because they can bring an understanding of human nature to a distillation of the true spirit of the message from the raw communication of it.6
And then I apply those words, not to the other programmer, but to myself. If I can’t explain my point to my fellow developers, at least I can listen to their point. It matters not in which brain communication begins; it matters only that it begins.
Next: Every Picture Tells a Story >>
More Practices Articles
More By Apress Publishing
|
 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.
|
|
/ 11 
