Ulterior Motive Lounge

I blame Microsoft

Martin L. Shoemaker — Wed, 01 Apr 2009 22:22:49 GMT

In a classic Dilbert strip, Tina the Tech Writer is forced to write docs for code that doesn’t exist yet. Her last line: “If you call our tech support, we’ll blame Microsoft.”

Works for me! I blame Microsoft for why I don’t have a new Lounge today. OK, so time spent job searching is a larger factor. But still, I’d rather blame Microsoft.

In particular, I blame Windows 7. Now by and large, I’m loving the Windows 7 beta. It’s a thousand little things I didn’t know I needed, but now I need. And it’s running amazingly well on my old Toshiba Portege M200. Soon I hope to test it on my Gateway, which has a lot more power.

But there’s one area where I’ve found a bug; and it’s a critical bug for the Lounge. In fact, it’s in the critical Lounge application: Windows Journal.

I love Windows Journal. It’s simple, it’s powerful, it’s free with Windows. You grab a Tablet PC pen, and you draw. That simple, and that powerful. Simple, because it just works like a pen and paper. Powerful, because even though it doesn’t have the drawing features of a higher-end paint package like Paint Shop Pro, it has two very powerful features:

You can print documents to it. Word docs, Excel spreadsheets, Web pages, whatever: print to Journal, and then you can draw on top of the “printed” document. I use this as a presenter: I print my Powerpoint slides to Journal, and then present from those. As I present, I can hand-write notes in answer to audience questions. This is the only way to present, in my opinion. (Actually, not quite the only way; but that’s an announcement I’m saving until I finish some code…)
You can do a text search of your hand-written notes. So not only can you write on your document, you can search for what you wrote. Again, this is great power for a presenter. (But again, look for an announcement soon…)

So I do love Journal. I call it the Killer Tablet PC App Microsoft Doesn’t Know They Have. Journal by itself is reason enough to have a Tablet PC, but Microsoft seldom seems to mention it. (A search for “Windows Journal” on Microsoft’s own site finds more hits for the Journal Viewer than for Journal itself; and Journal seems to have no specific page there, just a couple of “how to” articles.)

And I can’t draw the Lounge without Journal. Every episode, every panel, it’s all done in Journal.

And therein lies the problem: in Windows 7 beta, Journal is broken. When I open old episodes, some of the contents are drawn in the wrong place. Even worse, some aren’t. That means pieces of the episodes actually move around.

As an example, here’s Episode 32 as I drew it in Journal for Windows XP, then pasted into Paint Shop Pro for cropping and converting (click pictures for larger images):

Now it’s not high art, but it all looks like I intended it to look.

And here is how that page looks under Windows 7 beta Journal:

Notice the vertical stripe of missing Ink on the right. That’s bad. But it gets worse. Without me touching the image at all – all I did was switch to Paint Shop Pro to save the screen shot, switch to Live Writer to edit this post, and switch back – I get this:

I’m not sure I can describe all the things wrong with that image. Some parts of it have moved. Some parts haven’t: the panel borders are all drawn the same as the rest of the image, after all; and the nose of the Gremlin in panel 3 hasn’t moved at all. But the tail of the Gremlin has moved into panel 4!

Now a suggestion by Jennifer Marsman made me try an experiment; and her intuition is good: the Ink hasn’t actually moved, it’s just drawn in the wrong place! If I use the Journal selection tool and click in the image, I get this:

Notice how part of the Gremlin and passengers in panel 2 are really exactly where they belong; but they’re drawn to the right of where they belong. (Why only part? I can’t guess. I don’t know the internals of Journal. May be something to do with Grouping.)

Now Stacy Vicknair has asked if this bug is so bad that it stops me from drawing the Lounge? My answer is a definite maybe. See, I’m busy, and I’m lazy. If I draw something well enough once, I try to copy and paste it in other places where I need it. I’ve got 32 Episodes in, plus 3 Lounge-based conference talks and a Lounge book proposal. (Oops! Did I say that?) At this point, I probably draw less than half of each Episode. The rest is paste, resize, and edit. (I even wrote LoungeWorks, a set of Ink tools that give me power features not found in Journal: rotate, mirror, and scale.) But now, if I can’t reliably see where things are, it gets much harder to draw new Episodes. And with most of my time devoted to the job search, “harder” is not a feature for me right now.

I’m posting this in hopes of getting the attention of someone on the Journal team at Microsoft. I really want to use Windows 7, but I must have a working Journal for the Lounge. I’m not a fan of dual-booting, especially when my M200 has a rather small drive. I’ll dual boot if I have to; but I’d be happier to help Microsoft fix this. If anyone knows anyone on the Journal team, please pass the word: I’ll be happy to share the file that shows this bug, if that will help them to fix it.

I’ll also be happy to share another Journal file with an even more painful bug. Actually, I have multiple files with the same problem. They’re Web pages that I printed to Journal (XP) for later markup. If I try to open any of these in Win7 Journal, Journal hangs, and then Win7 terminates it. Worse: the recovery code “helpfully” tries to reopen that file next time I start Journal, and crashes again. Repeat, repeat, repeat, until I move the file so Journal can’t find it.

Journal team, I hope this helps! Contact me if you need more info. If you can’t figure out my email, you can always try @umlguy on Twitter.

Ulterior Motive Lounge Episode 32: Talking with Pilot

Martin L. Shoemaker — Wed, 04 Mar 2009 22:06:48 GMT

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

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:

And you would also see this diagram:

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:

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.
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:

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	Priority:	Difficulty:
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…

Ulterior Motive Lounge Episode 31: The Teams Split Up

Martin L. Shoemaker — Sat, 31 Jan 2009 06:59:22 GMT

Continuing The Project That Time Forgot, a UML case study in comic strip form... (Click pictures for larger images.)

After a long hiatus due to weather, illness, work, conferences, and more stuff than I can explain, the Lounge is back.

This Episode gets the ball rolling for Act II, so there’s not much new UML content here yet. But I can give you a few diagrams of the team’s review process. The process starts with some preliminaries, then splits into three threads of operations, each with a separate team:

Design Review. This team, led by The UML Guy, will create a Design Assessment, summarizing the state of the design and any clear risks and concerns. The details of the Design Review look like this:

Review the original design spec to determine the intent of the original team.
Review design documents and updates since the original spec.
Reverse engineer a design from the code. A good UML tool like Enterprise Architect makes this a lot easier, but not easy. VSTS 2010 will make it even easier, but still not easy. Incorporate this into a design summary.
Review the design with the dev team and revise until it’s ready for presentation.
Review the design with the full review team and revise until it’s ready for assessment.
Create the design assessment.

Functional Review. This team, led by Geek Girl, will create a Functional Assessment: a description of how well the system performs existing functions, with emphasis on usability and correctness. The details of the Functional Review process look like this:

Review the existing requirements docs.
Review outstanding defect reports, and make those the beginning of a functional assessment.
For each function identified in the requirements, identify actors and user who represent those actors. Interview those users to determine how well the system really works, and update the functional assessment.

Requirements Review. This team, led by The Reader, will create a Requirements Assessment: a description of what requirements the system covers; and more important, what it doesn’t cover. The details of the Requirements Review process look like this:

Review the existing requirements docs.
Assess the quality of the existing requirements. Are they quantified? Are they testable? Are they unambiguously stated in words, diagrams, and tests? Are they assigned business values and priorities? Do they have clearly identified actors and use cases and scenarios and goals for each feature? These and many more questions will help to create the requirements assessment.
For each actor represented in the requirements or discovered during interviews, identify and interview representative users. Determine whether they have missing requirements, as well as whether they know of or require previously unidentified actors.

For a really thorough review, you probably need at least three more threads of activity:

Code Review to inspect the code, either completely or through sampling, to identify how well it’s constructed and maintained.
Quality Review to identify Quality Assurance measures, Testing measures, and the status of each.
Process Review to analyze the processes followed by the dev team and related teams.

But for simplicity (and to keep most of my focus on my primary message), I’m going to restrict this case study to Design, Functionality, and Requirements. Code will be reviewed under Design, and Quality will be reviewed under Functionality. Process will be reviewed everywhere.

Is this a lot of work? Yep. But it’s a minimal necessary set of activities to review a project for status and risks after you’ve ignored them for a long time. It would be so much easier if you could do these sorts of assessments in real time right from the start as the project proceeds. It would be so much easier if you could report the status and health of the project at the push of a button, based upon the actual work the team does as they do it. Gee, wouldn’t Owner’s life be a lot easier if there were tools to do all that?

Oh, wait a minute… There are tools like that! In fact, there’s a whole category of such tools: Application Lifecycle Management (ALM). And my current favorite is the aforementioned Visual Studio Team System, perhaps the most poorly named product Microsoft produces today. Why poorly named? Because Visual Studio is a developer tool set, particularly a tool set for .NET developers; so when people hear a name like “Visual Studio Team System”, they assume it’s a developer tool set, only bigger and better. They assume it’s about .NET development.

VSTS is not about .NET development. Oh, VSTS includes Visual Studio, and then adds some powerful developer and architect and DBA and tester features; but those features, as powerful as they are, are just the icing on the cake.

The cake is ALM. VSTS is about your process and how you can define it and design it and manage it and track it, all through tools your team – your whole team, not just .NET developers – are already using. Your Project Managers can create task lists and project plans in Excel or Project. Your developers can work on those plans in Visual Studio – or not! If they’re working with Eclipse or other non-.NET tools, developers can use TeamPlain to access their work items. Testers can create and apply test plans. Executives can view summaries and reports and Key Productivity Indicators (KPIs) through a project Web portal.

And all of these tools are updated automatically as the team works, in real time, through the Team Foundation Server: a powerful set of databases, reports, services, and tools that integrate with Excel and Project and Visual Studio and Sharepoint and other tools to provide a seamless process involving all participants.

I didn’t intend this post to turn into an ad for VSTS, so I’ll leave you to explore further if you like. But I can tell you this: even if Owner had known about VSTS, even if he could’ve convinced Cowboy Consultant to look at it, they would’ve turned it down. Owner already balked at spending proper time and money on requirements and design. Cowboy Consultant already demonstrated that he has no patience for anything beyond the code itself. Well, as powerful as VSTS is, it’s not cheap (though I think it’s well cost justified), and it takes time and effort and training to use it properly. They both would’ve written it off as needless overhead, judging by the attitudes we’ve seen so far.

And those attitudes are going to lead to some mighty big problems pretty soon. Dinosaur sized, even.

One final note on today’s Episode. You may wonder why Dog is going out into the Park with The Reader and Stick Boy. Well, she’s a dog. She smells things, really interesting things. She wants to investigate, not hang around in some sterile, air conditioned computing center. Dogs gotta be walked, ya know?

Ulterior Motive Lounge: A Map of Carnivore Park

Martin L. Shoemaker — Sat, 10 Jan 2009 07:35:07 GMT

As I’ve written elsewhere, I love maps. And I love a story that includes maps. Maps help me to see where the action takes place; and they give me tantalizing clues to action yet ahead. When I first opened a hardcover of The Hobbit and unfolded the big map of Wilderland, I was hooked.

So for those who love maps like I do, here’s a map of Carnivore Park. (Click picture for a larger image.) This is where the rest of the story takes place; and following it is a map guide that may contain clues to what lies ahead.

Carnivore Park lies within a dormant volcanic island, bought and run by Owner. The volcano cone makes a natural barrier to dinosaurs – and to prying eyes, of course. The west end faces open ocean. The east end faces Central America, though a long way away. The east end beach has been artificially built up, along with two breakwaters. A concrete apron allows cargo and passengers to disembark and take the switchback up the slope to the entrance to The Park.

The interior of The Island may seem natural, but it’s actually nearly 100% sculpted or planted. The topsoil has been imported from rich fertile swamps on the mainland. The river has some contribution from springs and runoff, but is heavily fed by a hidden desalination plant. The ridge through the Park is actually a concrete wall, with interior chambers and bolt holes. The plateaus of the visitor center are partly natural, but largely shaped concrete. Roads run along the ridges, sometimes fenced from the dinosaurs, sometimes separated by “natural” barriers, and sometimes exposed.

The Visitor Port

Ship and helicopter landings.

Carnivore Park

The main park buildings reside on a set of artificially enhanced plateaus. Trees and other obstacles are carefully arranged to block any view of dinosaurs from the Pavilion or the rest of the control area; but the Lodge is elevated so that the higher (and more expensive) storeys have a view into the main Park.

The Pavilion

This is the entry to the Park. It includes the Operations Center, the Gift Shop, the Quick Bite Café, the Boring Exposition, and the Laboratories.

Gift Shop

Souvenir shop. Sells Park merchandise. Also sells LoungeWare.

Quick Bite Café

A cafeteria.Specializes in curried “dinosaur” dishes (actually chicken).

The Boring Exposition

Auditorium named for Wayne H. Boring. Used for reviews and presentations.

Operations Center

The nerve center for the Park.

The Laboratories

A sign on the door reads “Here there be dragons!”

The Lodge

Guest lodging at the Park. Across from The Pavilion.

Drumbeats

Nightclub at the top of The Lodge.

The Food Chain

Restaurant in The Lodge.

The Pool

A place to unwind when not out seeing the dinosaurs.

On The Rocks

Bar near The Pool.

The Petting Zoo

An area near the Pool where small, cute dinosaurs are available for petting and feeding.

The Park

A giant, dormant volcano cone, perfect for confining dinosaurs.

The Garden

Where the herbivores run “free”. Visitors can approach by ascending walking trails.

Carnivore Country

An area where various smaller carnivores roam.

Rex’s Crib

An area set aside for Tyrannosaurs Rex specimens, including extra reinforced fencing and other safeguards.

Raptor Country

An area dedicated to Velociraptors and their prey.

The Backlots

Fenced areas deep within the public viewing areas, well-screened by trees. These are areas where workers prepare and care for dinosaurs (and dinosaur meals) before release into the viewing areas. Each has a number of isolation pens, carefully screened by trees from other pens.

River Country

A boat tour (not yet approved by Money Man) through swamp and river dinosaur habitats. Also passes through The Glasshouse.

The Glasshouse

A large glass enclosure for flying dinos.

The Power Center

Includes a geothermal power station, water pumps, and fence control.

Ulterior Motive Lounge Episode 30: Touring the Laboratories

Martin L. Shoemaker — Wed, 07 Jan 2009 08:22:19 GMT

Continuing The Project That Time Forgot, a UML case study in comic strip form... (Click pictures for larger images.)

Here, for your convenience, is a larger version of the activity diagram from panel 2:

Figure 1: The Recipe for Growing a Dinosaur

And here is Editor Bill's comment on that diagram: "I hope in the commentary you plan to explain that this activity diagram tells the story of the rest of the Episode." Well, no, Editor Bill. I hoped that by now my readers were UML-savvy enough to figure that out on their own. You're not the only smart reader I have, you know? (Bloody Editor Bill's too smart, keeps figuring out my strategies before I can reveal them. Next thing you know, he's gonna grab my drawing pen. Uh-uh, no way, Editor Bill! This pen is mightier than the sword!)

That diagram is also almost a logical sequencing of the use cases from this diagram from the previous Episode:

Figure 2: Geneticist and Embryologist Use Cases

But that's a use case diagram, and the new diagram is an activity diagram. Which is the right way to show this information? Should we draw use cases, or should we draw activities?

Those who know me might guess that my answer is: Yes. (They've heard it too many times: "Whenever you ask me 'A' or 'B', I'll always answer 'Yes' or 'C'.") But in this case, my answer is more nuanced: "Whichever one communicates better; and that may mean drawing both of them." Which of course is a longer way of saying "Yes."

As I mentioned in Q&A #2: Battle of the Twitter Guest Stars!, one purpose for an activity diagram is to show what happens "inside" a use case. So the Figure 1 could be a diagram of what happens within this hypothetical use case:

Figure 3: The Grow Dinosaur Use Case

Why do I call this a hypothetical use case? Well, to my way of thinking, it's rather large. Based on what The UML Guy has learned about the laboratories, the process from DNA extraction to a dinosaur ready for release into the Park consists of multiple complex operations, possibly iterations of operations, over weeks to months. I like my use cases to be a lot smaller and more atomic than that. The use cases Isolate Sequence, Replicate Sequence, etc., look a lot more like use cases to me. Grow Dinosaur looks a lot bigger, like some large scale business process.

But here's where it gets a lot more complicated, and where I have to stop giving you easy answers. More important, I have to stop giving you just my answers, because I don't want you to be limited by my biases. I want to suggest other ways of looking at use cases. In fact, I'm seriously hoping that some of the Business Analysts in my audience will add comments and start a discussion, so that the rest of you can see the gamut of approaches to use case modeling.

Because here's the thing: many Business Analysts, including many I respect a lot, would say that Grow Dinosaur is about the right size for a use case. In fact, some might even claim that it's too small, and would prefer a more generalized use case like Care for Dinosaurs.

I once heard an experienced analyst say confidently he had worked on a very large system for a client, the largest system he had ever worked on. In fact, it was so large, it had fifteen use cases! Oh, that was for the entire business operations of a multinational corporation, so it had to be big. But just imagine, he said, fifteen use cases!

And I once heard another experienced analyst say just as confidently that the user interface he was modeling wasn't very complex. After all, it wasn't much more than a dozen or two use cases. That's tiny, right? He was used to working with 80 use cases in a system.

And here's the kicker: those two analysts, one who saw 15 as unimaginably huge and one who saw 24 as kind of small, worked for the same very respected consulting company.

In other words, there’s a lot of disagreement in the analyst community over the right level of granularity for use cases. Some see use cases like Shipping and Manage Personnel and Manage Facilities, while others see use cases like Order Supplies and Schedule Repairs. Some see use cases in individual button pushes. Who’s right? I dunno. I gave up trying to answer that question a long time ago. I listen to one point of view, and I say, “Hey, those arguments make a lot of sense!” Then I listen to another point of view, and I say, “Hey, those arguments make a lot of sense!” And then I put them together, and I say, “Hey, this doesn’t make any sense…”

I’ve decided that the difference isn’t in right or wrong, it’s in what level the analyst thinks at and is comfortable thinking at. Those who think at the enterprise level see enterprise use cases like Shipping and Manage Personnel and Manage Facilities. Those who think at the project level see project use cases like Order Supplies and Schedule Repair. Those who think at the UI level see use cases in individual button pushes. And all of those levels are valuable, and none is “right” or “wrong”.

But there’s probably a big difference in the level of documentation for different levels of use cases. The exhaustive level of detail prescribed by, say, Cockburn’s Writing Effective Use Cases may be appropriate for a use case like Manage Facilities; but it’s massive overkill for a use case like Log In. Business analysts have told me horror stories of 15-pages of documentation for Log In; and I’m fairly sure it’s because they were applying enterprise-level documentation practices to application-level use cases.

So in sum, I find the argument over the “proper” granularity of use cases to be pointless. Oh, for a given analysis project, that argument matters: an enterprise analysis effort can’t afford to get bogged down in use cases like Log In and Change Password, or they’ll have thousands of use cases; but an application analysis effort needs more detail than Manage Facilities (and less detail than 15 pages on Log In). But when I see arguments over the “proper” granularity, I can usually resolve them by discovering that the parties arguing are working at different levels.

And far more useful to me is this simple fact: the use case strategy, the use case way of thinking about requirements and solutions, is powerful at all levels of analysis. I’ve used this strategy from way out at the enterprise level all the way down to the level of individual classes. This strategy of saying “Who needs some work done? What’s the work? Who else participates? What information or objects are involved and affected?” has great probative power. If you want to say that Order Supplies isn’t a use case, fine. Call it a feature. Call it a function. Call it a benefit, an operation, a a method. Call it an Apatosaurus for all I care. I don’t care what you call it; I care how I think about it and describe it and figure out how to resolve it. And how I do that is the use case strategy. I’ll call it a use case, and you can laugh at me if you like.

But those who adamantly insist on a “proper” granularity will often also insist on a rule: “Thou shalt not decompose use cases.” And I’m going to completely ignore them when they say that, because to me it means, “Thou shalt not examine use cases at one level and think how they may be realized via use cases at a deeper level.” And as much as I’m loath to use such a black-and-white word as “wrong”, that’s just wrong. When I start to think about the problem at a deeper level, I will think about finer-granularity use cases that make up the use cases from the upper level. For example:

Figure 4: The Grow Dinosaur use case, plus detail use cases

In this use case diagram, I introduced some new UML notation: I added two boundaries. A UML boundary is just a box that groups related diagram elements. In this example, the boundaries represent two different perspectives on the system. Operations needs a strategic view. To them, growing a dinosaur is one task they want carried out: “Yeah, this is Ops Chief. We’re ready to start planning the Back Lot now. Could you start growing us some Velociraptors? Thanks!” From that strategic view, Grow Dinosaur is one use case. Meanwhile, the Laboratory sees a number of complex operations that they carry out on different samples and eggs and newborn dinosaurs. From their more tactical perspective, there are many dinosaur-related use cases. So I used the boundaries to help separate these perspectives while still showing them on a single diagram. To me, there’s great value in thinking at the strategic level and then moving to the tactical level, and even deeper. That means there’s great value in decomposing use cases. Others are free to disagree, but I’m going to keep doing it.

Other comments on today’s Episode…

Why does Dr. Gene carry around a giant DNA strand? Because I like it! It started life as the spiral staircase from Episode 25; and from there, it kind of grew unexpectedly. Sometimes things grow beyond our plans, and the unexpected happens. The same thing has been known to happen with dinosaur parks. And with comic strips…
Yes, I have seen UML diagrams adapted into marketing materials. After all, if a diagram communicates, it may communicate to the audience as well. Of course, most UML tools produce kind of bland diagrams, so the art department usually jazzes them up to the point where the modelers may no longer recognize them.
Editor Bill immediately saw the bad joke in panel 5; and he liked it, so I kept it. You can blame him. (But he wouldn’t let the crocodile say, “Ow!”)
Cladistics is the hierarchical classification of species based on evolutionary ancestry. You examine the DNA of different species and determine how closely related they are and when they diverged evolutionarily by how closely their DNA matches. It’s also the subject of a fascinating essay by Stephen Jay Gould. (“A fascinating essay by Stephen Jay Gould” may be one of the greatest redundancies I’ve ever written.) To my knowledge, there’s no such thing as cladistic reversal, but it seems like a really clever idea for recreating ancestral DNA by isolating it from descendant species. Hey, you have a better idea for growing dinosaurs, fine, you can open your own park. In my Park, they use cladistic reversal!
While cladistic reversal is fictitious, the lab equipment in panel 6 is certainly of the highest quality.
In the second page, notice that many of the dinosaurs have the Name : Class format for their labels, such as we first saw in Episode 15. Remember that we typically omit the name if there’s only one instance of a class in a diagram, particularly if the diagram shows what is true for all instances of the class. But when we want to examine different instances – in this case, different dinosaurs – and tell them apart, then we add names.
Despite the name (Carnivore Park), all of the dinosaurs in that last scene are herbivores. This is the safe, open section of the Park. Trust me, the carnivores are coming in Act II!

Ulterior Motive Lounge Episode 29: Touring the Pavilion

Martin L. Shoemaker — Tue, 16 Dec 2008 02:03:15 GMT

Continuing The Project That Time Forgot, a UML case study in comic strip form... (Click pictures for larger images.)

“We grow dinosaurs!” Big whoop, huh? Like anyone reading the strip hadn’t figured that out before I started Scene 1… It’s hard to surprise the characters in a story when the audience can tell from the promos what the surprise is.

But since The UML Guy has been part of the project before, none of this was a surprise to him. So while the others were taking in the new sights, he was drawing more UML diagrams. His results follow.

We learned a few more specific kinds of scientists on the project:

We added one more category of Employee Actors, Information Staff:

If you’ve ever eaten at a restaurant – certainly if you’ve ever worked at one – you’ll realize we need more detail in our set of Concession Actors, starting with a Restaurant Manager:

And then more specific Restaurant Staff:

We also learned of more systems we’ll need to support the functions described in the Episode:

We added an Information Console, a Laboratory Server, Laboratory Computers, Laboratory Devices, a Commerce Server, and Cash Registers. Note that the Commerce Server has to communicate with the Warehouse Server to schedule deliveries to the rooms and to the mainland.

These new systems complicated the physical Deployment Diagram almost to the breaking point. It’s complex enough that The UML Guy plans to group it, simplify it, and turn it into multiple diagrams when he gets time. But for now, here’s one more look at the single diagram:

We added some new Use Cases for Driver:

And for Guest:

One of those Use Cases, Make Purchase, is complex enough to deserve a dedicated diagram:

We can see from the Episode that there are multiple Classes of souvenirs:

And finally, we have new Use Cases for the Geneticist and the Embryologist. Normally, The UML Guy prefers a single diagram per Actor, focused on the Use Cases for that Actor; but in this case, the Use Cases are closely related and work with related Domain Objects. So he combined the diagrams for now, but may split them later:

That’s it for new UML content for this Episode. Oh, The UML Guy could imagine more, such as Use Cases for the Restaurant Staff and the Souvenir Staff; but Owner just didn’t give enough detail to work with. Those will come out over time.

Other comments on this Episode:

The sign post in panel 2 probably ought to include Seoul, Ottumwa, Mill Valley, Boston, and Crabapple Cove; but that would’ve made it unreadable.
It’s not the Dino Dog that’s bothering The Reader in panel 6, it’s the curry. The fastest way to drive him away is to serve him curry. But boy, curried chicken sausage sounds good to me right now!
Since you insisted (I know you’re thinking it, here’s the recipe for Yabanapple Soup:

Yabanapple Soup (Serves 4)

3 large ripe bananas

1 large sweet potato (sometimes called a yam in America, but not the same as yams elsewhere – it’s a whole different genus and species)

1 large can of chunk pineapple, drained

2 large cans of whole coconut milk (skim if you prefer)

3 tablespoons of honey

1 dash cinnamon

1 dash nutmeg

Clean and peel the sweet potato.
Boil a pan of water. When boiling, add the sweet potato, and boil until slightly soft. Remove from heat and drain.
Peel and slice the banana into quarter-inch slices.
Slice the sweet potato into quarter-inch slices, and then into chunks.
In a sauce pan, mix coconut milk, sweet potato chunks, banana slices, pineapple chunks, honey, cinnamon and nutmeg. Heat until simmering.
Serve hot; or chill and serve with a scoop of ice cream.

Boy, those are some cool-looking souvenirs in panel 7. Let’s take a closer look:

Wow! Too bad this is just a comic strip, not the real world. Wouldn’t it be great if there were a place where you could buy LoungeWare, especially just in time for Christmas?

Wayne H. Boring was a famous and popular Superman artist. I love his work, and I couldn’t resist borrowing his name for the pun in panel 8.

Next Episode: a tour of the Labs!

Ulterior Motive Lounge Episode 28: Meet Danny Diplodocus!

Martin L. Shoemaker — Wed, 10 Dec 2008 00:23:32 GMT

Continuing The Project That Time Forgot, a UML case study in comic strip form... (Click pictures for larger images.)

And just in case you can't read that sign above the gate, here's a larger view:

So Editor Bill looked at this strip and said, "Geez, Martin, what happened? You spent so much time drawing that volcano cone, you didn't have time for any UML?"*

"What?" I said, "You don't see the UML content in this Episode?"

"Well, yeah, there are a couple new systems mentioned, I guess."

"Ah," I said, "that's because you're not listening (or reading) with the ears (or eyes) of an analyst. This Episode is chock full of UML content. The UML Guy's listening carefully and updating his diagrams and drawing new diagrams. You just can't see that in the tiny little panels. But I'll be sure the readers can see them in the commentary." Score 1 for The UML Guy!

To start with, The UML Guy remembered the right name for one Actor. He kept blipping out on the name of the workers who load and unload the baggage; so he simply called them "Shipping Staff". Then he remembered the right name: Stevedore. So he updated the model for that, and also to show a previously forgotten Actor, Driver:

Editor Bill responded, "Drivers? I don't see any drivers. The team are just driving themselves."

"Ah," I reminded him, "don't forget: Actors in UML aren't people or job descriptions: they're roles people or systems play. In this Episode, Owner, The Reader, and Geek Girl are fulfilling the Driver role." Score 2 for The UML Guy! It's almost like I'm setting up these points on purpose...

Editor Bill mentioned a couple new systems. Oh, it's a lot more than a couple. Implicit and explicit in Owner's narration are 17 new systems. Score 3 for The UML Guy! That means our original Logical Deployment Diagram has grown by 242%:

Now some of those systems are implicit only because The UML Guy has worked on baggage handling systems and reservation systems. So these aren't requirements or existing infrastructure yet. They're only assumed.

That's OK. You're allowed to bring your experience and history to your projects. You're expected to bring them. Just be sure you don't mistake past experience for present knowledge. The UML Guy will have to present these ideas to Owner and Owner's staff and ask the analyst's most important question: "Is this right?"

And that's a hard question to get answered. It's easy for stakeholders to get confused in jargon and answer "Yes" out of reflex, not out of understanding. It's really easy for an analyst with a strong personality to unintentionally pressure the stakeholders into "Yes." I spend a lot of time saying, "Don't let me convince you that I'm right. If I'm wrong, please tell me. I don't think I'm wrong; but I need you to tell me if I am, because you're the only ones who can."

Now in this particular case, we're going to find that The UML Guy is brilliant, and these changes are all perfect. Scriptwriters have awesome powers, after all. (But I'd love to hear from you if you disagree with anything here.)

So the new systems are these:

Car Information System. This new system is obvious from the Episode.
Guest Information Server. If the Car Information Server is going to present guest-specific info feeds, somewhere there will have to be stored information on each Guest. Since the Central Server is concerned with operation of the Park systems, The UML Guy assumes there will be a separate system for Guest information. He's willing to be told that he's wrong, of course, but that's how he's drawing the diagrams right now.
Reservation Server. Since Owner discussed Priority Guests vs. Guests, we know there has to be a way for Guests to express their preferences as they make reservations. (See the Guest Use Cases below for more details.) That little bit of knowledge implies a reservation system of some kind. The Park will contract with a travel company to book reservations; and their Reservation Server will have to connect with the Guest Information Server to know what rooms are available when, and to inform the Park about reservations.
Guest's Personal PC. Guests will be able to make their reservations online, so their PCs are connected to the rest of the network by connecting to the Reservation Server. It's unlikely that we'll be deploying any code there; but again, we're defining a broad scope now, and narrowing in later.
Weather Station. Since the Island is an independent territory, there's no National Weather Service providing forecasts there. In order to provide up-to-date weather information, they'll need some sort of weather reporting station. Something like this...
Hospitality Console. The Lodge staff will need consoles to enter and maintain Guest information.
Event Planner Console. Event planners will need consoles to plan and manage events.
Room Lock. From Owner's description, the Lodge room locks must tie into the GPS system, since the GPS Locators act as keys; and the Guest Information Server must be able to assign GPS's to locks.
Sorter. The baggage sorter on the Island will be a huge system. (Trust me!) It needs a server dedicated just to sortation logic and planning.
Sorter Controller Module. While the Sorter plans and routes bags (and packages -- Park staff will use the same system for routing packages to installations throughout the Island), the actual sortation hardware needs a separate server to control all the inducts and diverts and carriers and rollers and conveyors and scanners and lifters and loaders and pushers and more and more and more... There's a lot there (Trust me!), so we'll need separate servers for routing logic and for device control and communications.
Bar Code Scanner. Each package will be tagged with a bar code label, and the scanners will use these to locate each package and report the locations to the Sorter Controller Module.
Sorter Car. Each car (or carrier) in the sortation system will have its own control device to help it induct, center, and divert loads.
Baggage Check In Console. When the Guests arrive at the docks on the mainland (or at the heliport for Priority Guests), the Stevedores there will have to check in their baggage at this console.
Baggage Scale. Weighs Guest luggage.
Bar Code Printer. Prints the bar code labels for the baggage.
Shoreside Baggage Server. Manages baggage information at the dock or the heliport.
Dockside Bar Code Scanner. Used to confirm that each bag reachs the dock and is loaded onto the ship.

And if the Logical Deployment Diagram has gotten complicated, the Physical Deployment Diagram has gotten worse -- so complex, The UML Guy had to reorganize it and regroup the nodes by their locations in (and out of ) the Park:

These locations are:

Underground Sortation System. Where all the sortation hardware is found.
Server Room. Where the primary servers are found. (Yes, I can explain why Room Lock is inside that boundary. It's a highly technical concept we call a mistake. The UML Guy goofed. He'll clean it up later.)
Lodge Offices. Where Lodge hardware is found (and probably where Room Lock should be found). It contains two specific locations:
- Concierge Office. Where the Hospitality team works.
- Event Planning Office. Where the Events team works.
Reservation Agent. The offices of the third-party reservation service.
Ops Center. Where the lead Ops staff works.
Comm Center. A separate building where communications hardware is found, including an array of communications towers and antennas mounted on the roof.
Check In. The baggage check-in centers on the mainland.
Field Units. Mobile devices throughout the Island.

And as The UML Guy added hardware and envisioned hardware in different locations, he realized the Park would need more Routers, along with a satellite Internet link; so he added those to this diagram.

The UML Guy also identified initial Use Cases for some Actors, including Driver:

This Use Case relates to two Domain Objects: the GPS Data, and the Guest Feed (which in turn involves a Weather report, Daily Events, and Guest Schedules). The UML Guy also added a note for a known defect. There may be better ways to note this, depending on your defect tracking tools; but this note is a very visible way to indicate it (expecially to my audience, i.e., you).

We also have Stevedore Use Cases:

The UML Guy didn't mark either of these with a defect note: even though he knows the sorter's not working, he doesn't know enough yet to tie it to a particular Use Case.

And finally, with have Use Cases for Guests and Priority Guests:

I could go through the Episode panel by panel and justify every one of those Use Cases; but most of them should be obvious if you've done much traveling. If you have any questions on them, please feel free to ask. The UML Guy probably has some idea of Event Planner and Concierge Use Cases from this Episode as well; but the information is so vague, he left those Actors for later. (Either that, or he was awed by the scenery.)

No UML content, Editor Bill? Ha! It is to laugh! UML content coming out your ears, my friend...

Some other notes on this Episode:

Yes, all cars on the Island are AMC Gremlin X's. Long-time readers will notice a pattern here.
Before I drew panel 4, I had no idea there would be Car Information Systems. Before I drew panel 5, I had never heard of Danny Diplodocus. Now this little bit of imaginary code is whispering in my ear and suggesting that he needs a larger role in the story. He's a blooming drawing of an imaginary blooming computer-animated dinosaur, and he's trying to wrest control of the story from me! I tell ya, authors have no control over their creations, none at all.
No offense is intended toward Italian software developers in their role in the defective sortation system. I'm not blaming them; but it's common for the absent team members to become the scapegoats for all failures, especially when they're from a different company and there's a bit of a language barrier. Do they share the blame in this case? Probably. Do they deserve the whole blame? I seriously doubt it. But since they're not there to defend themselves, they're going to get more than their share, I'll bet.

Next Episode: a tour of the Pavilion!

OK, OK, Editor Bill didn't say that. As author, I get to put words in the mouths of my characters and Editor Bill. He did say, "Well, no, there's not a lot of UML content; but you can be excused, because you've got a lot coming up." Then I told him about the UML content. But if I tell the story this way, I get to brag about how hard I worked on that volcano cone!

Ulterior Motive Lounge Episode 27: Meet the Crew

Martin L. Shoemaker — Fri, 05 Dec 2008 23:34:39 GMT

Continuing The Project That Time Forgot, a UML case study in comic strip form... (Click pictures for larger images.)

There's the business, and then there's the role of the system within the business. If all you focus on is the role of the system, you can miss chances to see where the system's really needed.

So time permitting, I would rather start by understanding the whole business and then work inward. Oh, sometimes the division is very clear: if my client asks for a change to their payroll system, I probably don't need details about their waste management system.

Or do I? What if the waste management staff is made up of hourly employees? What if excess waste problems can result in overtime? What if that overtime gets charged to a different budget, such as the Environmental Quality Initiative?

The boundaries between "business" and "problem domain" can be fuzzy, and it's easy to cross the boundaries without realizing it. I find it's easier to start with a broad scope and narrow in than to start with a narrow scope and expand.

And if I had to pick the number one category of overlooked Actors in requirements analysis, it's the development and maintenance teams themselves. Customers think about what they need from your system; but how often do they think about what you need from the system? Do they think about running diagnostics to chase down problems? Do they think about maintenance and archiving of data? Do they think about staging and deploying patches and new releases? Do they think about detecting and tracking defects and problems and patterns of usage and percentage of down time? Do they think about support personnel and the tools they'll need to keep users running?

Maybe. Maybe, if they're a very experienced system buyer. But most often, the answer is no. If you don't think of the development and maintenance and support staffs as Actors, and you don't identify their Use Cases, no one will. Then you'll deploy, and the system will need maintenance, and your users will need support, and you'll have no tools to help them. And when you start trying to retrofit the tools after the fact, someone will say "You should've thought of that." And they're right. You should have. You're the professionals here.

So Owner has done a good job of identifying the "stars" of the story. These are Actors you will see again as the story plays out. (Trust me: if I didn't need them in the story, I wouldn't draw them. I'm just too busy to draw characters I don't need. (Somewhere Editor Bill and Curtis Gray are stunned into disbelief at that remark.)) But he has barely scratched the surface of the full Park staff. After much longer discussions, The UML Guy identified these basic classes of Actors:

This is a common pattern in many of my models:

Users are anyone who might be involved with the system in any way. They may be anonymous visitors to the Park's Web site; or they may be more specific Actors, as described below.
Authorized Users are Users who have permissions to do something on the system that Users can't do. This is represented in the diagram above as a set of Authorizations. Different Authorized Users will have different Authorizations. We'll get more specific about what that means when we get closer to code.
An Employee is an Authorized User that works within the organization and has additional Authorizations as a result.
A Supervisor is an Employee with a Staff of Employees, along with additional Authorizations and responsibilities.
A Vendor is an Authorized User who isn't employed by the business, but who provides services to the organization and may have additional Authorizations and responsibilities.

In addition, this model has another class of Authorized Users: Guests. We want each Guest to have Web access to Park content, so that we can sell additional services and souvenirs to them. And then Priority Guests are Guests who pay for full Internet access.

After identifying these major classes of Actors, the team identified more specific versions of each. The Vendor Actors diagram is the simplest:

The Supervisor Actors are more numerous:

The Employee Actors are where the "Actor Explosion" comes in. This is just the first diagram; more detailed Employee diagrams follow:

Most (but not all) of these Employee classes have more detailed Employees below.

Here are the Ops Staff Actors:

And Ops Staff is complex enough to require two even more detailed diagrams. Here are the Transport Staff Actors:

And here are the Facilities Staff Actors:

Here are the Laboratory Staff Actors:

Here are the Lodge Staff Actors

Here are Concession Staff Actors:

Here are the Marketing Staff Actors:

And finally, here are the Medical Staff Actors:

Whew! That's a total of 86 different classes and subclasses of Actors! And I'll bet if I spoke to people in the transport, hospitality, marketing, or amusement industries, I'd find more. Owner's 8 Actors may be the most important, but they're less than 10% of the total set of Actors.

And I haven't even started looking at system and device actors. We'll likely end up with around 100 candidate Actors. Will we need all of them? Probably not. But I'm more comfortable now that we haven't overlooked anything.

And yet categorizing isn't enough! We really need to understand relations between them as well. For instance, Employees report to Supervisors. Here is a rough Org Chart for the Park staff, with an arrow from each Employee to the Supervisor to which she or he reports:

There's one more lesson in this Episode: although I see this work as identifying Actors, I went a little farther than that, identifying their goals and motivations as well. That's a step down the road to identifying Personas, as described by Alan Cooper in About Face and The Inmates Are Running the Asylum. In fact, since these are fictional characters, it's a lot like defining Personas. Cooper argues that by creating fictional Personas that represent users with personalities and motivations and goals, you create a filter to differentiate "okay software that someone can use" from "great software that will really satisfy this person's goals and make this person happy". I like a lot of what Cooper has to say in these books. I'm not 100% persuaded yet, but he's persuasive. Of course, I've also gone way overboard by his standards. He recommends typically around 3 Personas, 5 for a big project. I have 8, plus the review team, plus almost 80 more Actors. But I have them in part for the demands of the story, not the system. If Alan Cooper were doing Interaction Design for this project, he would likely focus on just one or two of these Actors, and flesh them out to a handful of Personas, and work on designing great software for them. Then he would focus on other Personas over time.

Ulterior Motive Lounge Episode 26: Aboard the Helicopters

Martin L. Shoemaker — Tue, 02 Dec 2008 14:59:21 GMT

Continuing The Project That Time Forgot, a UML case study in comic strip form... (Click picture for a larger image.)

This is the first we've seen of Deployment Diagrams in the Lounge; but they're enough like Class Diagrams that I think you should find them easy to read. Here's the diagram above, larger and more readable:

The cubes represent nodes within the system. By default, they represent Processors: computers where you'll deploy code. The <<device>> stereotype here indicates devices that your system talks to, but you don't actually deploy any code there. The lines connecting the nodes represent paths of communication. Recall from our Class Diagrams that we use arrows to indicate which end of a relationship is a "controller or "owner" in the relationship; but if the ends are "peers" -- or if we just haven't decided the details yet -- we use simple lines, not arrows. Lines are more common in Deployment Diagrams.

As in Class Diagrams, the triangle-headed arrow indicates generalization or inheritance. In this example, a Windows Mobile Phone is a more-specific example of a cell phone, one where we can deploy Windows Mobile apps.

Processors and devices are physical things. Stakeholders who haven't a clue what Classes they need will commonly have strong opinions of what nodes they need. "We're going to have PCs at all these stations, and a server back here, and two printers over here, and a connection to the Internet here, and..." So a Deployment Diagram is often part of their requirements, not just their design. (Of course, the design may result in deployment changes...) Drawing the Deployment Diagram is a good starting point for discussing the system.

To make these diagrams even more readable to the stakeholders, it's common to add specific icons for specific kinds of nodes:

What we've seen so far are logical Deployment Diagrams: these are the nodes that must communicate to carry out requirements, but not the full picture. A physical Deployment Diagram adds the hardware that connects these nodes, and also describes the connections:

Some stakeholders -- particularly IT staff and network admins -- will prefer the physical Deployment Diagrams; but most will prefer to know where work is done, without reference to how the nodes connect.

Note also some added detail here: besides Windows Mobile Phones, we have two other kinds of cellular devices. The Tablet PCs are equipped with Cellular Modems; and the GPS Locators use cell signals to broadcast their locations. Hmmm... That means the cellular network is very close to being a single point of failure. if that went down, it would be bad...

Other notes from today's Episode:

Dog refused to be left home. She's pretty stubborn sometimes.
WiMAX is becoming a very popular solution for wide-range wireless networking. But darn it, they still don't have a tower that can reach my house!
Stick Boy is a gamer geek. He never goes anywhere without his wizard staff.
Hacker Girl's shirt reads, "What-EVER!" in pink on blackl.

And finally: yes, despite his admonitions, The UML Guy just overlooked some vital information. He's not kidding: we all have blind spots, and we need each other to review and catch what we miss. Even knowing that, he didn't listen to Dog. She's always barking about something, so this can't be important, right?

Everyone on the team and every stakeholder has a unique perspective. Think of your problem as a giant abstract sculpture in a dark room; and you're supposed to recreate that sculpture. Everyone has a flashlight. Some are broad beams, and some are narrow, but none is large enough to encompass the entire sculpture. Oh, sure, if you stand back at a distance, you can play your beam over the wole thing; but then you're too far away to see details. So you need everyone, every light, to see angles and perspectives that you overlook. Even with all the beams, you'll miss some details; so go out of your way to get as many beams as possible, and have everyone look from multiple angles.

Of course, most of us would probably overlook Dog as a stakeholder, so I'll cut The UML Guy a little slack. But if only he had listened...

Ulterior Motive Lounge Episode 25: The UML Guy's Terms

Martin L. Shoemaker — Thu, 27 Nov 2008 01:04:00 GMT

Note: This was scheduled for tomorrow (hence the date drawn on the strip); but due to the U.S. Thanksgiving holiday, I'm releasing it a day early.

Continuing The Project That Time Forgot, a UML case study in comic strip form... (Click picture for a larger image.)

So in the previous Commentary, I wrote:

This Episode is all introduction. It doesn't include much UML content, and there's not much to add yet.

So naturally, this Episode has no UML content. But it was necessary to set the stage and to introduce common wisdom that somehow gets overlooked on project after project. I first saw this on the wall of a tire shop where my brother worked:

If you don't have time to do it right,
when will you have time to do it over?

So if they know that in the tire business, where the job is mostly well-defined, why don't we seem to know it in the software business with our nebulous requirements and goals? Oh, we say we know it; but when push comes to shove, we push and shove, when we should stop and think.

And push and shove is exactly the wrong thing to do! I know of no better metaphor for this way of thinking than Steve McConnell's pyramid builders (link is to a PDF). Please, please, please go read the whole thing! But here's the key description of the recurring problem:

The problem with the code-and-fix approach, as with the brute force approach to moving the stone block, is that quick movement off the starting line doesn’t necessarily translate into quick progress toward the finish line. The team that uses a more advanced approach is putting a framework in place that will allow the project to spin up to a high level of productivity and finish efficiently. It is putting rollers under the block, clearing the roadway, and preparing to focus the energy of the project team. The codeand-fix project gets the block moving early, but it doesn’t move the block far enough each day and the brute force approach isn’t sustainable. It typically leads to the creation of hundreds or thousands of defects early in the project. Several studies have found that project’s budget goes into fixing defects that were created earlier on the same project.

But that early "progress" is tempting. That early "progress" is seductive. That early "progress" is comforting, even if it's false. And most important, that early "progress" is visible. Stakeholders can see that things are happening. During up-front preparations, stakeholders can't see progress as easily, even if it's true progress, not just block-shoving.

So the situation shown in this Episode is common: stakeholders start out with enthusiasm for "doing the job right this time"; but then, when doing it right takes a long time and no code results, they get cold feet. They fall back onto "proven" techniques -- which mostly have proven to be difficult and costly; but because stakeholders get nervous, they grasp at tangible "progress" in lieu of visible progress.

Who do we blame for this? Do we blame the stakeholders? Nope. Oh, maybe a little: if they've been through this before, and it never worked before, then they should know better. A simple rule: if nothing ever changes, then nothing will ever change. But no, I don't think the stakeholders get the blame.

Do we blame Cowboy Consultant? Nope. Oh, he probably deserves some of the blame; but I'm reluctant to blame him, because at times I've been him. As Fred Brooks has noted, optimism is an occupational hazard of software development, and maybe even a necessary characteristic for surviving the field: the problems we face are so large and so complex and so interconnected that anyone who wasn't a foolish optimist would go find other work. It takes a certain mix of optimisim, hubris, and geekiness to throw yourself into the multidimensional problems that programmers tackle. So even though an experienced developer should know better, we all have a tendency to say, "Oh, that'll be fun! I can do that!". And then we leap in without thinking, before we even know what we're doing. But no, I don't think Cowboy Consultant gets the blame (but maybe a little of it).

So if we can't blame Owner, and we can't blame Cowboy Consultant, who do we blame? I can tell you who I blame in this case.

I blame The UML Guy. He really blew it.

Much of the disaster that looms in future Episodes could have been avoided had The UML Guy simply done one thing right the first time: make his work more visible and comprehensible to Owner, so Owner would want him to continue. When he worked for Owner before, he knew a lot of the power of modeling. He saw a lot of modeling benefits in his final code. But he was too isolated, and hadn't yet figured out that his processes must be open and visible and measurable and testable to the stakeholders. In other words, he hadn't yet figured out his primary message...

It's all about communication.

And yes, this is fiction (I've yet to be invited to consult on a project on a tropical island, darn it!); but in spirit, it's true. Even though I got a lot of use out of UML early on, I only saw the true power when I changed my focus from modeling to communicating through models. Then, and only then, did I start to become The UML Guy: a UML fanatic who today can barely carry on a development conversation without drawing some sort of diagram of what's in my brain. Heck, I find myself drawing diagrams for anything and everything, not just development. Remember: UML is not about software modeling; it's about system modeling, where system equals stucture plus behavior plus purpose. So I can use UML diagrams to communicate about many things in my business life and even in my personal life. It has become a language that I speak, not a tool that I use. And that brings a very different attitude. I don't think about UML, I think in UML.

Now all this discussion about modeling up front may sound like a direct attack on Agile Development. I'm sorry if that's how it sounds, but it's not. It's an attack on Agile Gone Awry. It's an attack on CAFÉ. I think Alan Cooper makes a strong case that requirements gathering and interaction design is a valuable precursor to Agile processes. Steve McConnell also makes a case that iterative or Agile work simply spreads this up front work across the iterations, and probably even increases the amount of up-front thinking (while also focusing the thinking, if you're doing it right.) Scott Ambler has written an entire book on the value and role of modeling in an Agile environment. And Martin Fowler, one of the original signatories to the Agile Manifesto, wrote perhaps the seminal book on UML.

I'm a big fan of Agile Development; but I think the idea that modeling and requirements analysis aren't Agile is just off base. In fact, I would contend that Agile UML is exactly what I've been promoting in the Lounge and elsewhere: UML as a language you speak, not a tool you buy and not a process you follow. In fact, some Agile practitioners who tell me they hate UML are really conflating it with the Unified Process and hating that. It's UP they're rejecting; but because they conflate the two, they entirely miss what UML is about. (And they're also misunderstanding the Unified Process, which in fact can be a very Agile process. But that's a discussion for another day.)

And I'm not a fan of Agile Gone Awry: Agile Development used as cover for cowboy coding. Sadly, I find that many shops that claim to be Agile are really just doing CAFÉ. Some developers will grab any excuse to avoid doing any process. They'd rather be coding. As I've said before, you have to honestly understand your process before you can judge or change your process.

So this Episode is The UML Guy's attempt to make up for past mistakes. He's more confident now. He knows that if he doesn't trust his team and his process, Owner never will either; and he knows the process has to be open and visible to Owner and everyone else, so they'll understand why it matters. Will he succeed? Owner starts out pretty skeptical, after all. We'll find out...

Some other notes on this Episode...

The computer in panel 2 is a Tablet PC. It's all The UML Guy uses these days. (And if you enjoy Ulterior Motive Lounge, thank Microsoft for creating Tablet PCs. I couldn't draw this strip without mine. Someday maybe I'll write a post on how I create a Lounge Episode. I also may someday do a post on the "art" of stickfiguration.)
The drinks in panel 2 are beer (on the right) and cranberry juice (on the left). The UML Guy doesn't know how you people can drink beer. The stuff smells vile. But he has friends who expect it in the Lounge.
Dog in panel 2 is a Welsh Terrier. You probably can't tell that from my stick figure art, but she is. She's friendly and loyal and cheerful. She also has a nose for critters, which may get her into trouble at some point.
The spiral staircase in panel 7 started with a simple problem. Well, two simple problems, really. First, the panel seemed kinda empty without it. (That's the same reason I added Dog to panel 2. Sometimes little things take on a big life of their own.) And second, in my map of the Lounge, I forgot to include space for The UML Guy's office. That led me to the idea of a basement office; and from there, a spiral staircase seemed natural. It's a good way to fit the stairs in a small space. But once I had the first version drawn (which was much simpler than this version), I thought, "Ya know, that stair edge and that hand rail with those support posts look a lot like a double-helix..." So expect to see those stairs again, or something like them, in a later Episode.
Editor Bill was puzzled by Geek Girl's nickname, "Terminator Barbie". Geek Girl will explain when she feels like it, and not until. (I explained the nickname to Jennifer Marsman, a real-life Geek Girl, and she approves. So I'm gonna keep the nickname.)

Next up: On the helicopter... In the mean time, remember: don't just do something, stand there!

Ulterior Motive Lounge

I blame Microsoft

Ulterior Motive Lounge Episode 32: Talking with Pilot

The Model Rule

Launch Car Information System

Ulterior Motive Lounge Episode 31: The Teams Split Up

Ulterior Motive Lounge: A Map of Carnivore Park

The Visitor Port

Carnivore Park

The Pavilion

Gift Shop

Quick Bite Café

The Boring Exposition

Operations Center

The Laboratories

The Lodge

Drumbeats

The Food Chain

The Pool

On The Rocks

The Petting Zoo

The Park

The Garden

Carnivore Country

Rex’s Crib

Raptor Country

The Backlots

River Country

The Glasshouse

The Power Center

Ulterior Motive Lounge Episode 30: Touring the Laboratories

Ulterior Motive Lounge Episode 29: Touring the Pavilion

Ulterior Motive Lounge Episode 28: Meet Danny Diplodocus!

Ulterior Motive Lounge Episode 27: Meet the Crew

Ulterior Motive Lounge Episode 26: Aboard the Helicopters

Ulterior Motive Lounge Episode 25: The UML Guy's Terms