The first in a series of excerpts from my next book. This antipattern was mentioned in Everyday UML, Installment 1: Identifying and Organizing Actors.

Anecdote: Programmers Are Weird!

Symptoms: Customers who get frustrated talking to developers who are working as analysts. The jargon and abstraction overwhelms them.

Context: Projects where programmers act as analysts (i.e., programmer-analysts) yet lack training or experience in customer communications. Usually not projects where the customers are also technical personnel.

Motivations:

• Programmers like technology, like to talk about it, and spend much of their time immersed in it. It forms a comfortable language for them, including standards and conventions that simplify and clarify communication.


• 
  
  
  
  

  Programmers further develop writing habits (i.e., coding standards) that help produce more readable and maintainable code. They internalize these habits and tend to use them across the span of development activities. Yet despite programmers’ “comfort level” with these habits, the habits can be completely confusing to regular people.

  Programmers develop writing habits that help produce more readable and maintainable code, but can be completely confusing to regular people.

  
  


• Programmers also like to work in the realm of abstractions: ideal cases and especially common cases that allow programmers to create a solution once and then apply it (with necessary modifications) across a wide range of cases.


• 
  
  
  
  

  Customers and end users tend to work in the world of the concrete: real, distinctive jobs to be done for real, distinctive clients – and with real, distinctive problems and complications and consequences that popup. While they may think about abstract general principles when they need to, their work biases them toward the concrete. Most end users don’t deal with abstractions to the degree that programmers do.

  While customers may think about abstract general principles when they need to, their work biases them toward the concrete.

  
  


• For various reasons – cost, trying to facilitate communication, and simply not knowing any better being chief among them – many development organizations have programmers serving as programmer-analysts, but without training as suggested under the Trained Analysts pattern.

Problem: The problem, I hope, is obvious: programmer jargon can confuse customers and end users. That’s not news to anyone, and it’s a major consideration in many of the patterns in this book. But I want to draw particular attention to two common but confusing programmer habits: coding standards and abstractions.

Programming standards lead programmers to write (and sometimes talk) in odd-but-precise ways that have specific meanings to computers. And beyond that, we (I can be as guilty as anyone) like to show how clever we are by using these odd formulations in non-technical settings. It becomes a form of in-joke: “Let me just access the ICashMachine interface over here so I can instantiate some cash objects.” Our fellow programmers get the joke, laugh, and probably then try to top us. And if regular people took at us funny, shake their heads, and mutter “Geeks,” we take it as a badge of honor. They don’t get the joke, but we do.

And those odd formations really do serve a useful purpose in code; but boy, do they look odd! We stick an “I” in front of anything we “talk” to: IAccount, IBankSystem , ILeasingCompany. And as the examples above show, we like to jam together longStringsOfWordsThatNameSomething, and to use funny capitalization when we do so. And we like to use odd punctuation combinations, such as “==”. “::”, “->”, and “///”.

And believe it or not, every one of those odd usages has a specific and useful meaning. I could teach it to you, even if you’re not a programmer. As a customer, you could learn how to understand it. But why should you have to? Those odd usages are designed to help us to talk to computers, not to people. Just because we geeks can understand them doesn’t mean those habits belong in a requirements discussion. And yet they often end up there. Even when they’re being serious, programmer-analysts who write documents and especially programmer-analysts who create models tend to sprinkle them liberally with coding standards, with their vision of how the code might look. That makes it harder for customers and end users to understand those documents. Since the audience for those documents is people, not computers, that’s just not a smart idea, no matter how compelling it seems to the programmers.

Customers could learn how to understand the arcane jargon of programmers. But why should they have to?

Abstraction is a more insidious problem, because it has some real benefits during analysis as well as some real drawbacks. It’s important for analysts (including programmer-analysts) to identify general principles, commonalities, and other abstractions that can aid their understanding of the problem domain. But it’s also important to realize that customers and end users may not think in those abstractions; and trying to force them to do so may actually hinder communication. It’s all right to introduce an abstraction into the conversation and see if it helps; but you have to be ready to fall back on the concrete if the abstract doesn’t work.

There’s another potential problem with abstractions during analysis: they’re often a sign that you’re designing, not analyzing. When programmer-analysts start seeing possible solution abstractions, they may introduce those into the requirements documents. Not only can this confuse customers and end users, but it can also lead stakeholders to assume that these design concepts are actually requirements (as discussed under the That’s Design, Not Analysis antipattern).

Solution Name: Speak English!

Solution: Fortunately, this is usually a self-correcting problem. Just remind programmer-analysts to rewrite their text or models and to revise their remarks to aim for a general audience. That should be enough to get them to correct themselves.

Remind programmer-analysts to rewrite their text or models and to revise their remarks to aim for a general audience.

In particular, ask programmer-analysts to strip out coding standards wherever they appear, unless the requirement they’re documenting is actually a coding requirement (such as a required interface or protocol or algorithm). And if they’re using abstractions that seem too far from your problem domain for you to understand, ask them to go back to specifics first. From there, ask them to talk you through to explain the benefits and purpose of the abstraction, including how they expect the abstraction will apply across a wide range of cases. And if they can’t do that, then explain to them that the abstraction may be useful as a design concept – and should be documented in their design notes – but is complicating matters when it comes to requirements.

Resulting Context: With a few reminders from customers and end users (and a few jokes at their expense, as needed), programmer-analysts should learn to communicate with a general audience.

Discussion: This antipattern can be a special case of another antipattern: The Department of Obfuscatory Verbiage. And the solution relies heavily on The Echo Effect: stakeholders have to let programmer-analysts know when they have failed to communicate. And the ultimate solution, of course, is Trained Analysts, whether they’re programmers by title or not.

This will be the first in a series of posts that will demonstrate simple use of the Unified Modeling Language in the context of a simple project. (Thanks to James Hudnall for the inspiration.)

What the Heck is UML?

For those who are new to the Unified Modeling Language (or UML), here's a very brief introduction. UML is essentially a set of blueprinting notations for various aspects of system design, with an emphasis on communication to customers, end users, and other developers. Sadly, a lot of software isn’t really designed in the traditional sense. If I gave you a pile of nails and lumber, I’ll bet you could build a decent doghouse by eye. You might build a decent house, but you’d probably want to draw a sketch, at least; and I’ll bet you’d never pass inspection without that sketch, whether you needed it or not. And if you tried to build a skyscraper without detailed plans, you’d never get it off the ground without it collapsing; and government types would shut you down before somebody got hurt. (Thanks to Steve McConnell for the analogy.)

Well, a lot of software is built with doghouse methods, even if it’s a skyscraper project. UML is an industry-standard set of diagram types and modeling syntax that help you draw the plans. It's a standard maintained by the Object Management Group. It won't solve all your problems, but it's a useful tool to help you progress from doghouses to skyscrapers.

Defining the Model

Before you begin modeling, it's always a good idea to identify the purpose of the model. That will help you to know the scope of your model and to thus limit and focus your work.

For this stage of Everyday UML, our model will be defined as follows:

This is a model of operations for Your Comic Source, a full-service comic and game store with both storefront and online sales and events.

Note that this model is described as a model of operations for the comic store. That implies that this is a business model, focused on the operations of the business as a whole, not just on the operations of the software. Remember my message from UML Applied and UML BootCamp:

UML is not about software design; it's about system design, where a system is structure with behavior and goals. And software is certainly one kind of system, but it's not the only kind.

And in this particular set of examples, the system will be the entirety of Your Comic Source.

A business model is only one kind of model you might construct with UML. We'll see other kinds of models in future installments of Everyday UML.

Brainstorming About Actors

It's time to introduce our first UML concept: actors. No, we're not talking John Cusack or Marisa Tomei here. In UML, an actor represents a person or system or event with which your system interacts. It's the things outside your system that either ask your system to do things, or that do things for your system, or both.

If I'm completely new to a problem domain, I'll start with a single actor, Customer, use that as a probe for finding use cases and then participating actors, and then use those actors to probe for more use cases and more participating actors, and so on. (I explain this approach in UML Applied.) But when you know something about the problem domain, it may be easier to start by brainstorming and listing candidate actors. This list won't be perfect: you'll miss some actors, and you'll list some that you'll end up never needing. But remember another lesson from UML Applied:

Don’t worry about being perfect all at once (or ever!). If you’re communicating, you’re using UML effectively. There’s always room for improvement; but don’t let imperfection stop you from progress. That’s a key point in learning UML and in applying UML as part of a process. Your designs will not be perfect; but as your team reviews them and you refine them, they will become good enough: good enough to build the system, good enough to guide the testing and the documentation, good enough to drive the management of the process. A team that waits for perfection is just as bad as a team that is wedded to code-and-fix: neither team produces an effective design that leads to a successful system. Remember: code-and-fix bad; design-and-fix good.

One look at my bookshelves should serve as proof that I've spent a lot of time in comic stores. So I felt pretty comfortable in modeling actors for Your Comic Source (a.k.a. YCS) as shown in Figure 1:




Figure 1: YCS Actors


The standard UML symbol for an actor is a stick figure (whether the actor represents a person or not.) Note that these actors don't appear in any particular order, as should be expected from brainstorming. These actors are described below:

• Bank System. A computer system at the bank. The YCS system will collaborate with this system for payments and other transactions.
  
• Browser. Someone who visits the YCS Web site but who isn't yet a Member.
  
• Customer. Someone who purchases comics or games at YCS, either in person or online.
  
• Gamemaster. This is a person who arranges and runs game events for Gamers.
  
• Gamer. A person who plays games at the YCS store. (Games stores often have space for regularly scheduled games, as a way to expand interest in those games and sell more products.)
  
• Manager. The person in charge of day-to-day operations at YCS.
  
• Member. This is a Web site visitor who has moved beyond Browser status by creating an account and identifying interests. When comics or games of interest to that Member are released, YCS will send out email notices. Members will also qualify for special discounts and deals.
  
• Publisher. A person or company who publishes comics for sale at YCS.
  
• Special Guest. An artist, writer, game designer, publisher, or other individual who will visit YCS for a special event such as a book signing or a talk.
  
• Staffer. Someone who works the shelves or the counter at YCS.
  
• Store Owner. The owner of YCS.
  
• Subscriber. Someone who signs up for and purchases particular comic books in advance, and whose books are then delivered automatically (either in person or via delivery service).
  
• Vendor. This actor represents a person or company that sells or distibutes or consigns products for sale by YCS. (Definitions: Sells = "YCS purchases the item directly. All future profits or losses accrue solely to YCS." Distributes = "YCS stocks the item, but does not purchase it. Upon sale, proceeds are split between distributer and YCS. After a period of time, YCS may return unsold items." Consigns = "Similar to distribution, but a one-time arrangement between YCS and a private individual.")
  
• Vendor System. A computer system owned or run by a Vendor. It will work with the YCS system to transact business.
  

Remember a key rule in regard to actors: an actor represents a role that individuals or systems may play, not any specific individual and not any specific job title. One person or system may fill multiple different actor roles at different times, and a single actor role may be filled by different people or systems at different times. For example, the owner of YCS may fill the Store Owner role primarily, but may also act as a Manager or even a Staffer from time to time.

Relating Actors

To repeat: the actors in Figure 1 appear in a scattershot stream-of-consciousness order, with no real thought about how particular actors might relate to each other. But actually, there's a lot of things we know about these actors already. Next we want to capture that knowledge. Some of these things are shown in Figure 2:



Figure s: YCS Actors (Reorganized)


There are two kinds of relationship shown here:

• Generalization. Sometimes also called specialization, inheritance, or subclassing. Shown with a triangle-headed arrow, this relationship between two actors indicates that one actor is a special case or special kind of another actor (the one to which the arrow points). For instance, Figure 2 says that a Publisher is a special kind of Vendor.
  
• Association. Shown with a line or arrow, this relationship between two actors indicates that the actors collaborate in some way. You should prefer a line when the two actors interact freely. You should prefer an arrow when one actor controls or "owns" the interactions. (We call this a "navigable association", perhaps because the UML standards committee is fond of multisyllables). In Figure 2, for example, there is a navigable association from Manager to Employee, indicating that a Manager has Employees that work for him or her. Note also that the association includes a measure of multiplicity on the Employee end (where it reads "0..*"). Multiplicity indicates how many actors of a given type are involved in the relationship. "*" indicates an unspecified number; so 0..* in our example means that a Manager might have any number of Employees (including 0 — maybe they all got fired?).
  

(Other types of relations are possible, as we'll see in future installments of Everyday UML.)

Note also that I added some new actors into Figure 2. These actors represent common behavior shared by a number of different actors, and let us describe the common behavior in a common way. This is an abstraction, and can be useful. But you have to be careful: too much abstraction too early can confuse your audience. (For more on this topic, see item 64: Geek Speak from my upcoming book, Requirements Patterns and Antipatterns: Best (and Worst) Practices for Defining Your Requirements, coming soon from Addison-Wesley.) These additional actors are:

• User. This actor represents behavior common to all users of the YCS Web site. (This is a simplified version of item 56: Extended Inverted Org Chart from Requirements Patterns and Antipatterns.)
  
• Authorized User. This actor represents users who have some level of privileges within the YCS Web site, such as editing their personal preferences, etc. (This is another element of Extended Inverted Org Chart.)
  
• Employee. This actor represents common behavior for all persons employed by YCS. (This is a simplified version of item 55: Inverted Org Chart from Requirements Patterns and Antipatterns.)
  

Organizing Actors

Notice how I drew lines around groups of actors in Figure 2, dividing them into groups by relations. That suggests better ways to organize the actors. But to organize them, I first need to introduce UML packages. A Package is simply a hierarchical subdivision of a model. It functions very much like a folder on your hard drive, letting you organize a large collection of things into smaller, more comprehensible collections of related things. The icon for a UML package even looks like a file folder, just like a folder on your hard drive.

Looking at Figure 2, it seems natural to me that we should organize the actors into the packages shown in Figure 3:




Figure 3: YCS Actor Packages


This is a stripped down version of item 48: Actor Hierarchy from Requirements Patterns and Antipatterns. The Human Actors package is split into two subpackages, as in Figure 4:




Figure 4: YCS Human Actors


The Users package models the various kinds of users, as in Figure 5:




Figure 5: YCS Users


The Customers package models the various kinds of customers, as in Figure 6:




Figure 6: YCS Customers


And finally, the Systems package shows systems with which YCS must interact, as in Figure 7:




Figure 7: Systems that Collaborate with YCS

Organizing Your Model

Well, that's enough about actors for now. This installment is already a lot longer than I intended. But there's one more topic I want to cover: where these actors fit in the larger model that we're creating. There are a lot of ways that you can organize a model. I like to use an organization scheme as shown in Figure 8:




Figure 8: Organizing Your Requirements


The Actors package contains all the work we've seen in this installment. The Domain Objects package will contain details on things and types of things of interest to the actors of YCS. The Use Cases package will show Use Cases: the operations that actors perform within YCS, including the business rules that apply to those operations. And the Architecture package will show software systems and interfaces that will support the use cases.

What's Next?

In my next installment of Everyday UML, we'll look at some domain objects. I can't give a schedule for that, so keep your eyes open!