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.

Continuing The Project that Time Forgot, a UML case study. (Click images for larger versions.)

Episode 32

On the surface, this Episode may seem almost social. Demented and sad, but social. But if you could join Hacker Girl, reading Geek Girl’s Tablet PC over her shoulder, you might see a different picture:

Interview with Pilot

And you would also see this diagram:

Driver Use Cases (2nd revision)

You saw a conversation. Geek Girl hopes that Pilot saw a conversation. But she saw an interview, and a chance to capture and model requirements. Let’s review the notation here and discuss the diagram contents.

  • The ellipses are the use cases that a driver performs (indicated by the arrows from Driver to the use cases).
  • Dependencies (dashed arrows) with the <<include>> stereotype indicate that one use case includes another within at least one of its scenarios. So in order to Get Destination, the system must Scan GPS IDs.
  • The triangle-headed arrows (generalizations) indicate that one use case is a special case of another use case. So Contact Ops via GPS, Get Time from CIS, and Get Weather from CIS each has a special case that uses Voice Command; and each of those special cases is defective.

You might ask: “Why is Maintain Car in this diagram? Aren’t they modeling what the computer systems will do? Does the computer have any role in car maintenance?” And that’s a legitimate question. If the team were modeling the entire business, Maintain Car would certainly be a use case in the model; but why did Geek Girl include it in the system requirements model?

The answer is two-fold:

  1. Pilot mentioned reflashing the engines, which is a computer-driven operation. As indicated in Geek Girl’s notes, it’s not clear at this time whether the Park’s computers are involved in reflashes or not. The reflashes may be done by dedicated tools that have no connection with Park systems; but it may be that the Park maintains records about the reflashes. Just in case, Geek Girl wanted to capture this.
  2. And building on 1: it’s always best to capture whatever a user says, even if you’re not sure it’s relevant. You can always remove it later. The analyst’s first job is to listen and capture. Analysis and filtering comes later. Don’t filter while you’re listening, filter later!

But then you might ask: “Why did Geek Girl stop there? Why didn’t she include use cases like Fly Helicopter and Rebuild Diesel Ferry Engine?” The answer is that she ignored what I just said, and she filtered now. “Filter later” is a good guideline, but you do have to apply some measure of judgment. Certainly “Watch Your Language” doesn’t involve the computer system, so she knew she could ignore that. Fly Helicopter and Rebuild Diesel Ferry Engine are less clear; but there’s certainly a good reason for leaving them off this diagram: it’s a diagram of Driver use cases, and those aren’t Driver functions. Pilot does them, true; but when he does, he’s not acting in the Driver role. Because remember: actors are roles people or things can play, not the people themselves; and one person or thing may play multiple roles.

If you’re still uncomfortable with the distinction between Maintain Car and Rebuild Diesel Ferry Engine, good! Welcome to the world of requirements analysis! There are no hard and fast rules. There are no clear lines, only guidelines. You have to apply judgment; but as a general rule, err on the side of capturing more information, not less. Geek Girl captured a lot of notes on her Tablet PC, while converting the most clearly relevant ones into a diagram. After the interview, Geek Girl will find time to clean up and reorganize the diagrams, and perhaps rethink the contents.

In Episode 28, The UML Guy adopted a convention of indicating defects via notes on diagrams, as in this earlier diagram of Driver Use Cases:

Driver Use Cases Scene 7

Harlan Ellison once observed that a lot of dumb behavior can be traced back to the phrase, “It seemed like a good idea at the time.” Well, Geek Girl has decided that The UML Guy’s good idea at the time is a bad idea going forward. Not that the notes are a bad practice: they clearly indicate the defect, and diagram readers can easily see what the defect is. If your goal is printable diagrams which stand on their own, this might be a good practice.

But it has some weaknesses:

  • As we find a lot more defects, the diagrams will get cluttered, and it will get harder and harder to arrange the diagrams legibly.
  • We have to do extra work to show the defect on additional diagrams.
  • Printable diagrams aren’t your goal, or shouldn’t be, in my opinion. To quote myself:

The Model Rule

We saw The Model Rule in chapter 1; but it bears repeating. To use UML effectively, you should never be simply drawing pretty pictures; you should always be editing an underlying model, using the pretty pictures as your user interface. Thus, the model should contain more information than is displayed in any one diagram; and information in one diagram should not explicitly contradict information in another diagram. Information that is found in one diagram but not in another should not be considered a contradiction. Rather, this simply indicates that the former diagram displays more detail than the latter. Details may be omitted from a given diagram to make it more comprehensible.

But how do you keep these diagrams consistent with each other? How do you maintain the underlying model? This is where a good modeling tool proves its worth: a good modeling tool will maintain the model as you create and edit your diagrams. If you are not using some sort of modeling tool, this very mechanical burden will fall on you, rather than on the machine. That’s a poor division of labor: brains should do brain work and machines should do mechanical work. If you do the mechanical work, you will do it imprecisely and inefficiently, and you’ll have no time for brain work. I urge you to investigate and use one of the many UML tools available. A list of UML tools can be found in Appendix B.

  • And building on The Model Rule, defect notes on the diagram don’t let your model and your tool help you in managing the defects. As an example, Enterprise Architect from Sparx Systems allows us to add detailed requirements information to each element of the model. Here’s a sample screen shot:


And then you can create a requirements report that lists the defects, as in this snippet:

Launch Car Information System

Satus: Proposed



Phase: 1.0

Version: 1.0


Defect #1: Startup is delayed.

That’s a lot of power to give up just for the minor benefit of notes on the diagrams. (There’s a lot more power in Enterprise Architect reports than I’ve shown here; and if that’s not enough, EA is an incredibly powerful automation environment. You can build add-ins for it, and also build automation clients that control your EA models. I have one in the works that lets you directly create EA models from Microsoft Word 2007 and Microsoft Office 2007. When I first started using EA, I said, “This is a great UML tool for the price!” Today, I know better: Enterprise Architect is a great UML tool for any price!)

So in place of defect notes on the diagram, Geek Girl prefers to note the defects in the model, as above; and then use a stereotype to show that the use case has a defect. I think that’s a better practice, even if it’s a bit tool-specific. It makes it easier to add the additional use cases that Pilot described in this Episode (omitting the domain objects so we can focus on the use cases and defects). And for me, The Model Rule is more important than printable diagrams, by a long shot.

And as for the last item in Geek Girl’s notes: yes, why is H.G. so hostile? That must wait for an upcoming Episode…

Posted on Wednesday, March 4, 2009 4:06 PM Ulterior Motive Lounge , It's all about communication. , Requirements Patterns and Antipatterns , Development Processes , Tablet PCs , Code is not Enough | Back to top

Comments on this post: Ulterior Motive Lounge Episode 32: Talking with Pilot

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

Copyright © Martin L. Shoemaker | Powered by: