Geeks With Blogs
Ulterior Motive Lounge UML Comics and more from Martin L. Shoemaker (The UML Guy),
Offering UML Instruction and Consulting for your projects and teams.

The point of UML – and I'll repeat this often – is communication. But there are different kinds of communication, even when the medium is the same. For example, speech is a very common communication medium; but there's a very wide range of speech styles that all manage to communicate. The stops and pauses and half-finished sentences and even grunts of a casual phone conversation between old friends are very different from the formal, scripted, ritualized sentences of a traditional marriage ceremony. Yet each is a successful style of communication.

So which should you prefer? Well, just imagine holding every conversation in your day with the same degree of formality and structure of a marriage rite. It would sound like parody:

"I, Martin, ask thee, Sandra, if thou wouldst enjoy a noon repast with me?"

"I, Sandra, ask thee, Martin, if thou may tarry a brief moment, and that thou might help me to escort our canines into yon field? Else, I fear, they shall do in our abode that which canines should do in fields."

"Yea, verily, shall I assist you in this, as in all endeavors. I shall fetch the Spaniel."

Pretty Picture

Compare this with an actual conversation: 

"Hey, Sandy, ready for lunch?"

"Just a minute. Help me take the dogs out first."

"Glad to! I'll grab Jake."

Legible Picture

The casual conversation ain't pretty. It ain't even grammatical, in every particular. And it leaves a lot unsaid, requiring the participants to fill in a lot of blanks. But it's real. And it's also economical (20 words vs. 72), and it gets the job done. Plus it's a lot easier to create. We create casual conversations on the fly, nearly as fast as our thoughts can flow. We create formal conversations by careful planning, thought, rehearsal, revision, and review. That slows down the fundamental process of thinking because the thinking is concentrated too much on form and not enough on substance. Now we cannot take this too far: we cannot casually invent words and usage any time we wish, without that also slowing down communication. We do so only when it serves a greater purpose, our ultimate purpose: communication.

That's the approach you should take to communicating with UML: legible over pretty, and standard over creative. Put in as much effort and as much customization as needed to get your point across; put in no effort on unnecessary prettification, and customize only when the standard notation fails to communicate efficiently. If you're drawing diagrams by hand, make the lines and shapes as straight and regular as you can, but don't break out the ruler and compass and protractor. (Fine-ruled graph paper helps a lot, though.) If you're drawing diagrams with a UML tool, stick to the easier features of the tool, and only use more esoteric features when necessary.

There's a place for pretty, just as there's a place for formal, ritualized speech. In fact, the places are the same: any occasion of ceremony, of transition. You can and should apply extra polish to diagrams that are to be presented in large, ceremonial settings (sign-off meetings, executive presentations, etc.), because it demonstrates attention to detail that will give participants confidence. No, strike that, they won't notice the detail; rather, if you don't apply the polish, they will notice the unpolished details, and their confidence will be shaken.

But in your day-to-day work, you should do exactly what I do in my day-to-day work: I get the diagram to the point where I think it makes sense; and then I hand it to someone else and ask if it actually does.

Maybe Even Ugly?

In case you haven't noticed by now, I see the primary value of UML in its role as a communication tool. But in Agile Modeling, Scott Ambler describes another value of UML. He talks of "modeling to communicate" vs. "modeling to understand". The latter is another perspective on the Outline Effect that I describe in my UML classes: a way of understanding a problem by building a model of the problem, or even of understanding existing code by building a model of it. This is certainly a valuable use for UML; but when you're modeling to understand, you may go even farther in the direction of legible vs. pretty. In fact, you may very well produce some pretty ugly diagrams.

Don't let this worry you, and don't let it slow you down. When you're trying to understand something, "cleaning up" diagrams will only distract you. If you can read it, it's good enough. Move on. Keep the momentum going. Making sense of a new problem domain is hard work. Making sense of existing code is even harder. Comprehension is hard, and neatness isn't always necessary for it. You can always clean up later, when your brain goes into idle and you're just going through the motions. I've spent many hours rearranging diagrams to make them more legible, while simultaneously listening to the TV or even taking part in a conversation. I don't want to imply that legibility is easy; but it doesn't take the same sort of intense concentration that's required for comprehension.


Posted on Saturday, November 15, 2008 3:00 PM It's all about communication. , UML | Back to top

Comments on this post: "Legible" does not mean "Pretty"

No comments posted yet.
Your comment:
 (will show your gravatar)

Copyright © Martin L. Shoemaker | Powered by: