Episode 3: Pestbusters II

Friday, September 26, 2008 – Three weeks of analysis, design, and testing later, Supervisor and The Reader meet in the Lounge.

 

Adding Collaborating Actors to a Use Case Diagram

Here we see our ideas from Episode 2 expanded and elaborated. Again, Use Case Diagrams are about requirements in context. Actors are persons or things that are outside your system but that interact with your system. By adding Collaborating Actors, you can show participants in the goals of an initiating Actor.
Who or what has to provide information as your system works through the Use Case? Who or what must be notified of the results?

And I emphasize or what. In our examples so far, the Actors have all been people (or Pest, who counts as a person for this example). But another computer system or device that participates in a Use Case also counts as an Actor from a requirements perspective. When we look at deployment, we’ll model these as systems or devices (there’s a surprise…); but from a requirements point of view, you probably do the same work when a person files a damage claim as when an automated system files the damage claim.

UML stereotypes and custom icons

Once I’ve explained this, you can easily grasp the concepts that Actor means outside person or thing and stick figure means Actor. So if you were working on my current client’s project (diagnostic systems for Harley-Davidson motorcycles[1]), you would be comfortable with this image:

 

 

 

 

But Use Case Diagrams aren’t just for you! As I discuss below, your customers should review these to help you validate them. And I guarantee that when my end customers see this picture, they’re gonna ask, “Who’s this person called Motorcycle? Is that the rider, or the owner, or the technician, or…?” UML is all about communication, and I just failed to communicate.

There’s an answer for this, and it’s found in UML stereotypes. A stereotype is a custom extension to the UML notation. From a UML perspective, a stick figure called Motorcycle is perfectly sensible. UML has no need for a special notation just for motorcycles. But my project does. So in my Motorcycle Diagnostics model, I added a stereotype: <<motorcycle>>. UML uses <<double angle brackets>> to indicate stereotypes. When you define a stereotype, you’re defining your own local “dialect” of UML.

Now that I’ve explained that notation, it’s easy for you to pick out the motorcycles in this picture:

 

 

 

 

But when the customers look at this diagram, once again they’re gonna ask, “Who are these people? The riders?”
For as long as people have been drawing pictures, “stick figure” has meant “person”. Don’t expect that to change just because you’re now speaking UML.

But never fear! UML can be further extended by defining a custom icon for a given stereotype. When you have nonhuman Actors, you can increase the readability of your diagrams a lot by creating custom icons. For instance, there’s no confusion when my customers look at this diagram:

 

 

 

That is communication. Bad art, but communication.

In fact, this comic strip is full of stereotypes from start to finish. Every character in this strip should be a simple stick figure, like Technician in the diagram above. But that wouldn’t be nearly as much fun.

Who is the audience for UML diagrams?

I’m often asked that question: “Who should read these diagrams? Who are we drawing them for?”

And the response I often hear, even before I can answer, is “Ewww, these are complicated. Let’s just keep these to the development team.
And whatever you do, don’t show them to the customers! That will scare them away!”

The question and the response are natural if you think of UML in the wrong way, the way I think is all too common: as a technology discipline.
It’s not. I’m gonna say this again (and again, and again, and…): It’s all about communication.
So the answer to “Who should read these diagrams?” is “Who are you communicating with?”

Now specific diagrams may be better suited to some audiences than to others. In my first speech class, Mrs. Roberts taught us the importance of MAP:

  • Medium: What medium are you using to convey your message? (Medium can also include setting.)
  • Audience: Who are you trying to convey it to?
  • Purpose: Why are you conveying it?

Your Purpose will vary at different points in your process. Sometimes you’re trying to understand user needs, and sometimes you’re trying to work out complex implementation issues. And different messages are aimed at different Audiences. If you’re discussing requirements, your Audience includes
customers and end users. For that audience, Use Case Diagrams are entirely appropriate if you draw them in the customer’s language.

In later Episodes, we’ll see Activity Diagrams. Again, those are very appropriate for customers, because they’re just pictures of the customer’s business rules. We’ll add Swimlanes to these, representing parts of the system. Those may be appropriate for customers, depending on whether they’re
“visible” parts or “internal” parts. We’ll see Class Diagrams, which can be appropriate for customers, depending on the level of detail.

Who is the Audience for UML diagrams? The best answer I can give is the Universal Answer: “It depends…”

[1] As described at http://www.spx.com/Archive/pdf/ideas_in_action/Harley%20Davidson_08.pdf.

Episode 2: Who Ya Gonna Call?

Thursday, September 25, 2008 – The UML Guy really gets into Use Case Diagrams!

 

 

 

 

 

Some useful Use Case Diagrams

In this diagram, we see some truly useful Use Case Diagrams. These diagrams are about requirements in context. Too often, we receive requirements as just a bulleted list of features, or a bulleted “The system shall…” list: “The system shall allow users to file receipts. The system shall reconcile receipts against outstanding invoices. The system shall become so convoluted and ill-defined that there’s no chance you’ll ever implement it correctly.”

These bullet lists aren’t bad (well, some are…), but they’re incomplete. They don’t tell you who requires specific features, nor what goals they want to accomplish through those features. As a description of requirements, they’re a starting point at best. Too often, they’re a trap: seemingly complete, but not.

Use Case analysis is all about putting requirements into a context. Who needs this feature? Why do they need it? How will they use it? What will they produce with it? How will they know it’s correct? How often will they use it? What steps will they follow? What rules and constraints apply? Who else will be involved?

There are a lot of techniques in good Use Case analysis, much more than can be captured in a simple diagram (or in a comic strip). Cockburn has a lot to teach on that subject. [1] But good Use Case Diagrams are a starting point. And busy teams may find they can’t squeeze in time for the Full Cockburn on every Use Case, but can use the diagrams to discuss which Use Cases require more detailed analysis. Agile teams in particular may prefer this approach, because Agile Development emphasizes the minimum documentation needed to successfully meet the requirements. Obsessively following the Full Cockburn (perhaps due to management dictate) can end up with 15 pages of documentation for Log In, without any actual code. It’s more Agile to start with Use Case Diagrams, and then add more detail where you find it’s necessary. Don’t underanalyze, but definitely don’t overanalyze.

I should add: there’s no UML reason I couldn’t have put all these Use Cases and Actors into one big diagram. I see it done all the time. And most of the time, it’s a mistake (in my opinion). The diagram gets too big, with too much going on. Individual details get lost in the confusion. Even though you drew it as one diagram, readers end up reading it as smaller diagrams within the diagram, focusing just on one Actor and that Actor’s Use Cases at a time. So it’s better to draw it as separate diagrams in the first place. (You’re not gonna listen to me. I know that. But I’m telling you what my experience has been.)

[1] Alistair Cockburn, Writing Effective Use Cases (ISBN 0201702258).

 

 

 

Episode 1: Friday Night in Ulterior Motive Lounge

Wednesday, September 24, 2008 – The Reader, a harried project lead, wishes he could get his development under control.

A first Use Case Diagram

This Episode introduces the absolute minimum useful Use Case Diagram. If it seems simple, it is. I want to show you that “speaking” UML is easy, if you start simple and grow. I don’t want to overpromise. UML isn’t a cure-all. It’s just a tool for communication. Let me repeat: It’s all about communication.

And if this diagram seems trivial, well, keep reading! We’ll get more complex.

And if you don’t understand the porkpie hat and Swingin’ on a Star, you should go rent Bruce Willis’s masterpiece, Hudson Hawk. You’ll love me for it, or you’ll hate me; but you won’t easily forget it.

UML in One Minute

UML is all about communication. It’s a diagram-based Language.

UML is not a process. It can be used in any process, from ad hoc to Agile to Orchestrated Development.

UML is not a tool. You don’t need Microsoft Word to speak, read, and write English. You don’t need any tool to “speak” UML. (But a good tool can make it easier!)

UML is not like the Oxford English Dictionary. It’s not formal, unless you need to be formal.

UML is a diagram-based language for building Models.

 

 

 

UML is not about code. It’s not even about software design. It’s about models of systems, where…

  • System = Structure + Behavior + Purpose.
  • Structure is expressed in Class Diagrams, Component Diagrams, Deployment Diagrams, and more.
  • Behavior is expressed in Activity Diagrams, State Diagrams, Sequence Diagrams, Communication Diagrams, and more.
  • Purpose is expressed in Use Case Diagrams, Activity Diagrams, State Diagrams, and more.

UML is a diagram-based language for building models using a Unified notation.

UML incorporates best of breed from prior notations.

Elements in one diagram can appear in other diagrams and add more detail.

One kind of diagram can add detail to another kind of diagram if you choose to use it that way.

These messages bear repeating. Expect me to repeat them.

A Slightly Twisted Introduction to The Unified Modeling Language…

2009 Introduction

After a decade of teaching UML, I find one thing really frustrating: people think UML is hard.

I can explain why they think that. There are many factors, too many to go into here.
But it frustrates me, because I know that communicating through UML is easy.

Sometimes friends even try to compliment me. “Sure, it’s easy for you, Martin. But you’re weird.” (Some friends, huh?) “It’s easy for you, because you’re smart. You get it. But it’s hard for us.” And though I appreciate their intended compliment, I don’t accept it. I ain’t special, and I ain’t smart.

Anyone can use UML as effectively as I do. I just have more practice, and a freakish willingness to be wrong if that’s what it takes to be right.

So I’m always looking for ways to shake people out of their preconceptions and get them thinking UML; and I’m not above using a little attitude to do so. I was preparing talks for a conference, and I knew I wanted to pitch a talk on UML for Agile Development. But a title like that just screams Bo-ring! It doesn’t challenge the attendee to show up and be shaken. On a whim, I came up with the title Everything You Know About UML is Wrong (But We Can Fix You)[1].

And then (as if the title wasn’t cheeky enough) in the abstract I promised to show attendees UML in a whole new way, with exercises and visual aids and dancing elephants. (Well, maybe not the elephants…)

And as soon as I clicked the Submit button, I realized: “Hey, what if they accept this talk? I’m actually gonna have to follow through on these promises!
Hey, that sounds hard! Visual aids? What was I thinking?”

And so I sat. And I thought. And I surfed the Internet. And I thought some more. And I surfed some more. And let me just be honest, I surfed more than I thought. (Admit it: you’ve done the same thing. The Internet is the world’s biggest time sucker…)

But somehow despite all that surfing, a thought still somehow swam out of my subconscious: an animated stick figure speaking about UML.

That thought survived for about three seconds before common sense clubbed it over the head, shouting, “You can barely draw stick figures, Moron! How are you going to make animations?”

But then I realized that I can draw stick figures (with a lot of help from Windows Journal[2]). They wouldn’t have to be animated as long as they were interesting.

And suddenly, panel 6 of Episode 1 sprung into my head, cold cocked common sense, and said, “I am your visual aid, Moron!” (All the voices in my head call me Moron. Don’t tell the doctors in the white coats, OK?) Before I knew it, almost all of Episode 1 was in my head, ready to be drawn. Almost all, with one key element still waiting for me to discover it.

So I had my visual aid concept; but I felt like I had more than just some conference slides. I felt there was a story here, even an ongoing story. That meant I needed a name. And I wanted the name to have a very specific abbreviation. (Please don’t make me spell it out! Let me pretend it’s still my private little joke – a very public private little joke.) In a late night Live[3] chat with my good friend Curtis Gray[4], he suggested a lot of L-words.
When he struck on “Lounge”, a shiver ran through me. I saw the bar. I saw The Reader and The UML Guy standing by the bar, talking. I saw The Bartender behind the bar. And somehow, behind me and to my left, I felt a round room with a central fireplace.
I knew this place that hadn’t existed moments before. “Lounge” it would be!

So that meant I needed a U and an M. I tried looking up possibilities online, only to discover that online dictionaries[5] are optimized for fast definitions, not for browsing by letter. So I dug back through my bookshelves and found an old curiosity: a paper dictionary! Leafing through the Us, I wasn’t thrilled with most of the earlier choices. Then I came to “ulterior”; and in the usage example, naturally, it included “ulterior motive”. (Come on: when was the last time you heard “ulterior” without it being immediately followed by “motive”?) That was it: the right initials and a hint at a larger purpose.

And thus, Ulterior Motive Lounge was born. I was only 90% sure at first; but I quickly reached 110%. The name fits.

So I had a name, a concept, a plot outline, even a location. With the help of Windows Journal, I had straight lines and rectangles and smooth ellipses. It was time to start drawing.

But after Episode 1 was drawn (or so I thought), I still was missing something. I just couldn’t tell what. So again, I let my mind wander; and I recalled a recent discussion where I had – for the umpteenth time – tried to convince a friend that Hudson Hawk[6] is an underappreciated comic masterpiece. (It is. Just accept that, and we’ll get along fine.) And suddenly, the missing element fell into place. I’ll let you read the Episode to see the results,
but I had a motif: Bad 80s Movies. Oh, all right, Hudson Hawk is a 90s movie, and not a bad one. But it’s 80s-ish. The real motif is “Movie jokes that make Martin laugh.” (The bunny slippers came later. I would ditch them if I could, but Curtis won’t let me.)

And so I added the missing pieces to the first Episode; and then I sought opinions from my buddy Bill Emerson, a.k.a. Epee Bill.[7] Before Bill quite knew what had happened, he joined the strip as the off-panel Editor Bill. Curtis became my beta tester, the voice of The Reader,
letting me know when I missed the balance between entertaining and educating. (Surprisingly, he most often criticizes me for educating too much.
He says that if I stop entertaining, he stops reading, and I stop educating. Less is more, I guess…)

And the Lounge was born. I announced it on Twitter[8], and got a much warmer reception than I deserved. In particular, tweeps @coreyhaines[9], @jbkazoo[10], @anklebuster[11], and @crazeegeekchick[12] fed my ego, with lots of comments and agreeing to guest star in the strip. Thanks to their promotional assistance, the Lounge received over 3,000 page views in the first 14 episodes. That plus their comments persuaded me to keep drawing and keep teaching. I can’t thank them enough!

I also was inspired by these YouTube videos: Animator vs. Animation (http://www.youtube.com/watch?v=c24t7Onr_Pw) and The One by mkrepps (http://www.youtube.com/watch?v=TuRjO8WbgT8), music by Gaelic Storm[13] (my current favorite band). Further inspiration came from Scott Adams[14], Jolly R. Blackburn[15], and Chris Muir[16], who convinced me that limited art skills are no barrier to telling graphic stories. (Yes, they’re all better than me; but what kind of standard is that?)

Various friends have made comments and suggestions on the Episodes; and when I used those, I credited them in the text. Some of them even appear as guest stars. Others have contributed without knowing, by teaching me lessons that I teach again here. Without them, the Lounge wouldn’t be what it is. (No, I’m not trying to shift blame, just acknowledge their invaluable assistance.) Here are the contributors, in order of contribution:

Curtis Gray
Bill Emerson (a.k.a. Editor Bill, a.k.a. Epee Bill)
Nancy Roberts, speech teacher and debate coach extraordinaire
John Burns (a.k.a. @jbkazoo)
Dean Esmay
Lynn Molenkamp (a.k.a. Lynn the Build Queen)
Ernie Walters (a.k.a. Ernie Out in the Barn)
Scott Morris (a.k.a. Scott the Integration Architect, a.k.a Scott the Prototype Analyst)
Christian Gross (a.k.a. Christian the Patterns Guy)
Dana Coffey (a.k.a. @crazeegeekchick)
Virginia Reiser
Lucy Reiser
Mitch Allen (a.k.a. @anklebuster)
Corey Haines (a.k.a. @coreyhaines)
Alan Richardson (a.k.a. Evil Tester)
Harry Gilbert
Scott Favre (a.k.a. @dfavre)
Andy Stampor (a.k.a. @arphahat)
Phil Newsted
Steve Stark

Thanks to Bruce Willis for the porkpie hat, and for the Hawk.

Thanks to my sister, Anita Buckowing, for invaluable proofreading. After all these years, she’s immune to my jokes. Mostly.

And thanks to Sandy for watching all these movies with me, for agreeing to be my wife, and for being my inspiration. Even when I don’t say it.

2020 Introduction

You won’t find me on Twitter much these days. The format is too restrictive. So all references to Twitter herein should be considered ancient history. All links are suspect.

Today, I’m not just a programmer, I’m a writer, as is obvious from this web site; and I find that a lot of what I wrote here applies to the writing world as well.

 

 

[1] Inspired by the Firesign Theatre album Everything You Know Is Wrong (http://en.wikipedia.org/wiki/Everything_You_Know_Is_Wrong).

[2] Windows Journal is a simple Tablet PC drawing tool available on all Tablet PCs, as well as PCs with Windows Vista and Windows 7.

[3] Live Messenger, available through http://www.live.com.

[4] Curtis Gray is a programmer, architect, salesman, and entrepreneur. You can hear some of our conversations on development at http://www.ShipItOnTheSide.com.

[5] http://www.dictionary.com, for one.

[6] Hudson Hawk (http://www.imdb.com/title/tt0102070/) is a classic comedy adventure story of an innocent cat burglar trapped in the crime of the centuries.
Ignore any review you’ve heard to the contrary.

[7] Epee Bill is one of my many long-standing friends from the Ann Arbor Dueling Society (http://www.AADuelist.org/club). He’s also a natural-born requirements analyst.
Some day, I’ll find a way to pay him to do that work, unless someone smarter than me snaps him up first.

[8] http://www.Twitter is a broadcast messaging system that’s very popular in the development community, and a source of much encouragement for the Lounge. Messages you post to Twitter are called “tweets”, and friends you follow on Twitter are called “tweeps”. (Don’t blame me, I didn’t come up with the names.) Tweeps are identified by their Twitter handles, which start with @ so that Twitter can mark them as links. You can follow me on Twitter by looking for @umlguy.

[9] Corey Haines (@coreyhaines) is an Agile Development enthusiast who looks for ways to advance and promote best practices in Agile.
He makes Agile personal, touring the country to help teams get hands-on experience with Agile techniques, particularly pair programming.

[10] John Burns (@jbkazoo) is a developer working primarily in educational support, and also an educator.
You can read his thoughts on life, development, music, and the environment at http://www.aviewofthemarsh.us/.

[11] Mitch Allen (@anklebuster) is a developer and game enthusiast, maker of the powerful MorphoBoard game design tool (http://www.morphodesigns.com/).

[12] Dana Coffey (@crazeegeekchick) is an ASP.NET Insider and active in the development community.
You can keep up with her, her work, her dogs, and her family at http://www.crazeegeekchick.com/.

[13] Gaelic Storm (http://www.GaelicStorm.com) is an American Celtic/pop band, best known for their work on the film Titanic.

[14] Creator of Dilbert (http://www.Dilbert.com), a documentary about life in the world of corporate engineering.
If you don’t think it’s a documentary, take it from those of us who’ve lived these stories.

[15] Creator of Knights of the Dinner Table (http://www.kenzerco.com/), a documentary about the world of tabletop role-playing games. If you don’t think it’s a documentary…

[16] Creator of Day by Day (http://www.DayByDayCartoon.com), an online comic of social and political commentary.