Home arrow Practices arrow Page 8 - Pragmatic Guidelines: Diagrams That Work

Summary - Practices

Unified Modeling Language is about communication. But in order for communication to work, it must be useful. How do you make sure that you don't sweat over a set of UML diagrams only to discover that no one else can understand them? Fortunately, there are guidelines, discussed in this article, to help prevent this catastrophe. This article is excerpted from chapter three of the book UML Applied: A .NET Perspective, written by Martin L. Shoemaker (Apress, 2004; ISBN: 1590590872).

  1. Pragmatic Guidelines: Diagrams That Work
  2. The Model Rule
  3. The MTB Rule
  4. The Résumé Rule
  5. Every Picture Tells a Story
  6. Define Your Own UML with Stereotypes
  7. Just Enough Modeling: Analysis, Not Paralysis
  8. Summary
By: Apress Publishing
Rating: starstarstarstarstar / 11
August 11, 2005

print this article



In this chapter, I’ve given you a set of practical “golden rules” to some of the issues that you’ll be dealing with as you begin to analyze your problem domain and develop your model. These are summarized here:

  • Do What Works

    The first rule is self-explanatory. There’s no point rigidly 
    obeying the rules if your model fails to communicate itself to 
    others, so do whatever works for you in your particular 
  • The Model Rule

    UML diagrams are like a user interface into your underlying   model. Different diagrams illustrate different aspects of the  model, and so they will contain different information, but the   complete set should present a coherent picture. Completeness   lies in the model, not in a single diagram.

     •  Legible Does Not Mean Pretty

Don’t spend an age getting your diagrams perfect: they only 
need to look good enough to get across the information that 
they are designed to communicate.

  • The MTB Rule (MTB—Minimum Two Brains)

 When you’re working on a new model or idea, always get 
 another member of the team to look at it. They might spot 
 flaws in a model that you didn’t, or help you to correct a 
 diagram. Two or more brains can spark a creative process.

  •  The 7 ± 2 Rule

  The average human brain can only hold 7 ± 2 things in its 
  short-term memory, so cluttered diagrams lead to confusion.
  Simplifying diagrams and reducing the number of elements
  often improves communication. When circumstances demand
  complexity, grouping related elembirtents can aid

  •  The Résumé Rule

        Each diagram should fit onto one standard-sized sheet of paper.

  •  "You just Don't Get It!" Is Never an Excuse

It’s your responsibility to ensure information is communicated. When there’s a problem, listen to the other people, and find out what they understand and where they think the problem lies. Make sure they can communicate the idea back to you.

    •   Every Picture Tells a Story

Every diagram should tell a story in its own right. All the details on that diagram should contribute to that particular story.

  • The Highway Map Rule

        Your models are maps to your code, so maintain them alongside
        your code, even after it has built. Although they might become
        a little out of step at times, don’t throw them away.

     •   Define Your Own UML with Stereotypes

         UML doesn’t contain a symbol for everything that you need.
         Sometimes it’s helpful to define your own symbols or add extra
         information to elements using UML stereotypes, but always
         check first that there’s not already something defined that you
         can use, or commonly, conventionally used stereotypes.

     •   Just Enough Modeling: Analysis, Not Paralysis

         Your model will never be completely perfect, and sooner or later
         you need to start coding. Learn to recognize when you have
         created a “good enough” model. Holes and other problems will
         show themselves up in review.

We’re going to come back to the process of analysis and design again in Chapter 5, when we look at gathering and analyzing requirements, but because I want to focus on how you can apply modeling and UML in a .NET environment, let’s take some time out first to see what .NET itself looks like as a UML model. That’s going to be the focus of the next chapter.

1.  Scott W. Ambler, Agile Modeling: Effective Practices for eXtreme 
     Programming and the Unified Process
(John Wiley & Sons, 2002)

2.  Jeff Del Papa, and The New England Rubbish Deconstruction
     Society, “The NERDS
Tactical Rules for Scrapheap Challenges
     (Project Management for 10 Hour Projects),”
The New England
     Rubbish Deconstruction Society Web site (
). Along with The MTB
, this site has some great practical rules for software
     development and management: “KISS. Keep It Simple, Stupid.”
     “Just  remember:
If brute force doesn’t work, you aren’t using
     enough.” “If you break, you lose.” “MCF:
Mission Critical First.”
     “Test Early, Test Often.” “Leave margins.” “Identify your hidden

     assumptions.” “The machine shop should be a last resort.” “Make
     time for silliness.” “If
something isn’t right—LET THE DIRECTOR
     KNOW RIGHT AWAY!!!” These rules are stated
in the context of a
     high-pressure hardware effort; but the spirit of these rules applies
software as well.

3.  Stephen King, On Writing (Pocket Books, 2002), p. 103. King goes
     on to demonstrate what
he means by writing as telepathy; and he
     makes a compelling (if metaphorical) case.

4.  George A. Miller, Ph.D., “The Magical Number Seven, Plus or Minus
     Two: Some Limits
on Our Capacity for Processing 
     Information,” (

5.  Robert A. Heinlein, Stranger in a Strange Land (Ace Books, 1991), 
     p. 266: “‘Grok’ means to
understand so thoroughly that the
     observer becomes part of the process being observed—
to merge,
     to blend, to intermarry, to lose personal identity in group
     experience.” In this
usage, grokking the whole picture is to see in
     it something beyond its individual elements.

6.  Jim McCarthy, Dynamics of Software Development: “Don’t Flip the
     Bozo Bit” and 53 More Rules for Delivering Great Software on Time

     (Microsoft Press, 1995), pp. 30–32. The
communication issue is
     discussed in depth under “Rule #4: Don’t Flip the Bozo Bit.”

     McCarthy’s point in this rule is that assuming that anyone is a
     bozo—i.e., they just don’t
get it—is destructive for that person
     and for the entire team. If they have the skills to make a

     contribution to the team, they have a valuable perspective to
     bring to any problem; and if
you cut off the chance for them to
     make that contribution, you might just as well cut them
loose from
     the team. Never assume your fellow programmers are bozos.

7.   Martin Fowler et al., Refactoring: Improving the Design of Existing
(Addison-Wesley, 1999)

8.   In Agile Modeling (p. 171), Ambler argues—correctly, I believe—
     that they still ended up with
a notation that is too large and
     bloated for most developers to use completely. Most modelers
     only a fraction of the entire language. A large part of the UML 2.0
     effort is to identify the
"core” elements of UML.

>>> More Practices Articles          >>> More By Apress Publishing

blog comments powered by Disqus
escort Bursa Bursa escort Antalya eskort


- Calculating Development Project Costs
- More Techniques for Finding Things
- Finding Things
- Finishing the System`s Outlines
- The System in So Many Words
- Basic Data Types and Calculations
- What`s the Address? Pointers
- Design with ArgoUML
- Pragmatic Guidelines: Diagrams That Work
- Five-Step UML: OOAD for Short Attention Span...
- Five-Step UML: OOAD for Short Attention Span...
- Introducing UML: Object-Oriented Analysis an...
- Class and Object Diagrams
- Class Relationships
- Classes

Developer Shed Affiliates


Dev Shed Tutorial Topics: