In the world of use cases, there's this thing called an include relationship. It's an advanced technique that is avoided as often as it is misused - which is to say, a lot. But the include relationship can make you more productive - so it's good to have in your toolkit of use case writing skills.

What Is It?

As the name implies, the include relationship is a relationship that can exist between two use cases. It allows you to insert the behavior from one use case into another. In other words, at some point in Use Case A, you'd jump over to Use Case B, move through those steps, then return back to where you left off in Use Case A.

When Do You Use It?

When writing use cases, you’ll find situations where you have the same exact steps in two or more use cases. For example, in a hotel reservation system, you might find that both the Cancel Reservation use case and the CheckIn Reservation use case need to perform the same steps to find a reservation.

When this happens, you could just write the identical behavior in each use case. Yes, you'd have a bit of redundancy and if the common behavior changes, you'll have to update it in two places. If there are just a few shared steps (say, three or less), then this is the right approach. The cost of creating the include relationship probably won't outweigh the benefits.

If, however, you have more than a few shared steps between two use cases, the redundancy becomes a waste of effort and you'll run the risk of forgetting to keep the duplicate steps synchronized. In this situation, employ the include relationship: Take the steps that are common, move them into their own use case, then include this use case in the place where the steps originally appeared.

Notation and Terms

The use case diagram below shows the UML notation to indicate when one use case includes another. In this example, Find Reservation is the included use case; CheckIn a Reservation and Cancel Reservation are the including use cases.

What's the Downside?

An important benefit of the use case approach is that it makes your requirements easier to comprehend. But the include relationship scatters behavior between multiple use cases - a practice you should avoid as best you can. Requiring your readers to look in more than one place to understand a use case makes the use cases harder to follow. It’s faster and easier to understand a use case if it's all in one place.

In short, the include relationship benefits the author at the expense of the reader. So like any useful technique, it should be applied judiciously.

A Final Pitfall

Do not use the include relationship to simply separate one big use case into a sequence of smaller use cases. If you do, you'll force your readers to look in multiple places just to understand a single use case. This misses the point of making requirements easier to understand. Your use case is just too big. Rethink its scope and rewrite it.

The include relationship is a great technique to have in your toolkit of use case writing skills. Are you using it to remove redundancy from your use cases? Are you encountering any challenges? Tell me about it by leaving a comment here.

Here at Serlio, we're pretty excited to announce that CaseComplete 2009 is now available. Here are a few of the new features.

CaseComplete and Microsoft Excel

We now integrate very nicely with Microsoft Excel. You can import existing requirements directly from Excel into CaseComplete. You can generate reports in Excel format (we previously supported HTML and Word reports).

So with this new integration, we included a bunch of templates out-of-the-box that we think you'll find useful. Things like:

• A project dashboard based on your use cases and requirements.
• A traceability matrix between the different kinds of information in your requirements (for example, between use cases and the requirements they refer to). 
• The CaseComplete Estimator - a sophisticated tool that predicts the effort required to implement your project, allowing you to try out different "what-if" scenarios.
• Test plans generated from your use cases and requirements.
• You could also use these reports as an easy linkage from CaseComplete into whatever test managment tool you're using.

There are 15 Excel templates included in this release. And you can create your own Excel templates to slice-and-dice information about your requirements in whatever way works for you.

Do More With Requirements

Based on the most popular requests from our customers, we enhanced what you can do with requirements . So you can now organize requirements into parent-child relationships. You'd use this wherever several child requirements need to be met in order to fulfill a higher level requirement. Requirements can now also reference other requirements. And referenced requirements can be shown on a diagram with a reference relationship.

Try It Today

These are just a few of the things we've put into the 2009 release. We've really tried to make CaseComplete the fastest, easiest way to create use cases and requirements. Try out the fully-functional 30-day free trial. Let us know what you think by leaving a comment here.

Are you into use cases? Are you on LinkedIn? (You probably should be.) Join other smart, cheerful people like you who share a common interest in use cases and requirements gathering.

The Use Case Professionals Group on LinkedIn is an online community for analysts, project managers, and others who are looking to learn and talk about how to gather requirements effectively with use cases.

It's a great place to ask a question, share what you know, or catch up on the latest industry news and blog posts.

At times, gathering requirements can be tedious, difficult, and not much fun. Not nearly as fun as using stick figures and shapes to tell a story. Giving in to creativity like this is so appealing that my three-year-old daughter does it without prompting. She just likes to draw pictures that tell stories. So do I.

Thus, I remain convinced that the allure of use cases is rooted in the idea that requirements can now be specified by simply drawing shapes and arrows on a diagram. Gone are the days of laboring through the process of gathering and managing countless requirements spread throughout different documents. It seems too good to be true. Because it is.

In reality, those details will still exist in the information behind the simple figures on your diagram. But if all that detail is still there, why bother with the diagrams? Well, let's talk about what a use case diagram is and what role it plays in specifying requirements.

What's On a Use Case Diagram

Use case diagrams have just three things on them:

• Actors
• Use cases
• Relationships

That's it. The stick figures symbolize actors - the roles played by users of the system. The ovals symbolize use cases - the things actors accomplish with the system. The lines show how actors and use cases are related. In the example above, we can see that a Subscriber can Read articles or Leave comments; only Authors can Post articles; and Moderators can Moderate comments.

The most important word in the previous paragraph is symbolize. On the diagram, those ovals aren't actually use cases. Each oval is an indicator that a use case exists - the detail that describes the use case is still there, written in textual form and somehow linked to that oval. The link might be supported by a tool - or it might exist only in your mind.

At the risk of insulting use case experts - I want to clear up a common misconception among people new to use cases. A use case diagram is NOT like a flow chart. The diagram is not meant to show the sequence of steps an actor takes when using the system.

Why Create Use Case Diagrams?

If you're thinking that use case diagrams seem a tad simple, it's because they are. They don't contain a lot of information. So why bother creating them?

These diagrams are yet another way the use case approach differs from traditional methods of gathering requirements. The use case diagram is a roadmap, a high-level view of the requirements that exist in the system. No other approach to gathering requirements has this element.

The purpose of gathering requirements is to communicate. As I said at the beginning of this post, requirements gathering can be tedious, difficult, and not much fun. Requirements grow to contain a lot of detail and and become increasingly more difficult to communicate and understand.

Use case diagrams make requirements more approachable and understandable by allowing someone to quickly visualize what the system needs to do. They allow you to brainstorm at a whiteboard as you decide what major functions your system needs to perform. In short, use case diagrams make it easier to communicate your requirements.

Being a use case expert has less to do with drawing stick men and ovals than it has to do with writing. Creating use cases is, at its heart, a form of writing. A good use case, like good writing, is easy to read. But good writing is not easy writing. In fact, the opposite is usually true.

The building block of a use case is the step. A use case is made up of all the steps an actor takes to get something done with the system. To write a good use case, we need to write good steps. So what makes a good step?

Use case writing is a bit like story telling. Seriously. We're telling our readers a story about one way an actor will use the system we're specifying. For the story to be readable, it needs to be well-paced. And pace is controlled by the steps in the use case. Each step should be neither too detailed (fine-grained) nor vague (coarse-grained).

Fine-Grained Steps

First, there is the issue of fine-grained steps. Early in a project, when my enthusiasm is still high, I'm hungry for the sense of progress that comes from capturing lots of detail. So I write very detailed steps, like the ones in this Find Reservation use case:

Writing with too much detail brings two major problems: 1) I'm constantly rewriting because small details change more frequently than bigger concepts and 2) the pace of the use case becomes tedious and slow. It's nearly impossible to keep the main flow down to six-to-ten steps. Most importantly, the reader has to work harder in order to fully understand the entire use case.

Coarse-Grained Steps

Next, there is the problem of steps that are too vague. Later in the a project, when my enthusiasm wanes and the focus turns to hitting a deadline, I slip into writing vague, high-level steps, like these:

Vague steps reduce the amount of work for me, the use case writer. But these steps leave out facts that are important to my readers - especially developers and testers.

Just Right Steps

So what's the key to writing steps that are neither too detailed nor too course, but just right? Make each step describe one of two things:

• What action the actor needs to take, or
• What work the system is doing for the actor (write the what, not the how)

Write each step as a simple declarative sentence beginning with either the name of the actor or the system (that is, ActorName verb object or The System verb object). I then wind up with a use case that reads like this:

Following these guidelines, the story behind each use case moves quickly enough to be readable without missing important detail.

Once I'm ready to get down to the business of writing a use case, I ask myself a few questions: How big should this use case be? Where should it begin? Where should it end?

If a use case is too big, it'll be hard to understand. If it's too small, I'll wind up with too many use cases and it'll be hard to see the big picture. Here are four guidelines to help answer these questions and get the scope of your use cases just right.

To help illustrate the guidelines, consider the sample use cases shown here. They involve the system a cashier uses at your local supermarket.

#1 - Based on a goal. A use case describes how an actor uses the system to achieve a goal. In the example, the Scan Item use case is suspicious. Scanning an item sounds like a step - not a goal. On its own, scanning an item probably doesn't add measurable business value. If I wrote all of my use cases at this level, I'd wind up with way too many.

When faced with a use case at this low-level, ask why the actor is performing the step. The answer will often point towards the real goal.

#2 Complete or not complete. When an actor has performed the steps in a use case, the goal should be either 100% complete or 0% complete. Not somewhere in between. If a use case is so long that it could finish in varying states (that is, some of the goals achieved), then it's probably too big. The Work Shift use case in the example probably fails this test. The cashier has multiple goals that need to be met in the course of working a shift.

#3 One person, one place, one time, one event. Try to write use cases that describe how one actor responds to one event in one place at one time. The Work Shift use case seems to break this guideline. It sounds like it could take a long time and encompass many events. So it would probably wind up being too long and complex grasp in a few minutes. (While it's possible to write summary-level use cases aimed at higher-level goals, I'll leave that as an advanced topic for another day.)

#4 Six to ten steps. Try to keep the main success scenario (aka primary flow) of a use case between six and ten steps. Use cases should make requirements easier to comprehend. While there's nothing magical about 6-10 steps, it seems to be the sweet spot between writing a use case that is too small to deliver value (Scan Item) and too big grasp all at once (Work Shift).

Follow these four guidelines and you'll be on your way to writing use cases that your readers will understand without losing sight of the big picture.

I'm a longtime reader of both Joel Spolsky and Jeff Atwood. I think their writing is great. So I've been closely following a website they've been collaborating on for the past few months: stackoverflow.com. It's a Q&A site with voting and editing features that make it more effective and useful than other sites in the same category.

Since stackoverflow is programming-centric, I didn't expect to see discussions on requirements or use cases. So I was surprised to find a referral to our website on a question about CaseComplete. And imagine my delight to find the response below:

After much research we settled on using Case Complete for a fairly large and complex project and haven't looked back since, it is both easy to use and intuitive. The document generation has been especially helpful.

We store all the project files/artifacts in subversion so that multiple people can work on the case complete project at one time. We have templates that generate our documentation from case complete projects, no maintaining of massive word documents.

I would definitely recommend it.

Thanks to the author for the positive feedback - we're glad you're having some success with our tool.

So the next time you have a question on software requirements or use cases, consider posting it on stackoverflow.com.

In truth, you won't actually need a lot of the things you fantasize you'll need.
from Signal vs Noise

Much of the Requirements Management Tools market (or more broadly the Application Lifecycle Management Tools market) relies on fantasy. People fantasize about things they think they'll need in a tool. They imagine how well their projects will run once they own the tool. They convince themselves to buy the tool. This fantasy is often supported by a the tool vendor's sales team.

I've worked with a lot of companies who have invested in such tools. My experiences have been eerily similar:

When I ask how they're applying the toolset, I'm met with slight embarrassment. They explain how they're not really using the tool to its fullest. Yet. But that they really intend to do better. They think more training or governance might help. They assume their situation is unique - that their peers at other companies are actually using all the features and doing all of the things that they're supposed to do.

Unfortunately, this the norm, not the exception. When building CaseComplete, we took a step back and asked what we really needed in a requirements tool. If we wanted to build a tool that people would actually use, what would it look like? This led us towards a few principles:

• Communicate - Don't Document. The point of gathering requirements is not to produce dry, unreadable documents - the point is to communicate. The tool should make it easier to share ideas - whether on paper, on your computer screen, on an LCD projected for a group, or whatever. The tool should make it easy to communicate what problem you're trying to solve and what the solution will be.
  
• Be Productive Immediately. In reality, most people don't even use a specialized tool for gathering requirements. They use a word processor and a spreadsheet and share these documents amongst themselves.
  
  Getting started with the tool should be as easy as firing up your word processor. You shouldn't have to submit a help desk ticket to get an account. Or get a week of formal training. Or wait for a system administrator to set up a project for you. Like your word processor, you should be able to fire it up and start gathering requirements in minutes.
  
• Capture the right info. The out-of-the-box experience for the tool shouldn't be a blank slate. Nor should it be a rigid template leaving you wondering what information you should populate into a field. The tool should guide you through gathering the right information at the right time. And since gathering requirements involves capturing different pieces of related information, the tool should capture those linkages too.
  
• Requirements Shouldn't Become a Burden. Gathering requirements isn't a matter of writing things down. It's a process of discovery. So we should expect our requirements to be in a state of continuous change. As the amount of requirements that we've captured grows, it shouldn't get harder and harder to change. The tool should make that easy for us - keeping all the linkages and relationships and ordering in place, making it easy for us to see the impact of our changes.

We tried to achieve all of these principles when we built CaseComplete and we're still trying to find ways to make it better. Let us know what you think - and tell us what you really need in a requirements management tool.

In the world of use case modeling, there is this concept of an actor. Actors are the things (human or otherwise) outside of your system that will interact with it in some way.

Actors are not real people – they are the roles that those people (or systems or things) play. They are an abstract concept, but during analysis, most of us prefer to spend our time thinking about concrete solutions – not about abstract concepts. So it’s easy to skip the effort that should've been spent exploring, identifying, and describing all of the actors in the system. Don’t do this.

To explain why, let me begin with a confession: I became interested in use cases because it was hard for me to absorb the traditional requirements specifications I had to read in order to do my job. I wasn’t sure if it was my short attention span or the fact that the software requirements specification (SRS) in front of me was as exciting to read as my mobile-phone contract. An SRS can drone on, page after page, numbered sub-item after sub-item, making assertion after assertion without ever talking about who is using the system or why they are using it.

We write down requirements to communicate – to spread information – about how we’re going to solve a problem. On its own, a traditional SRS is an awful way to spread information. It's dense with information – a list of unnaturally worded statements that doesn't easily show how they relate. No wonder I had a hard time absorbing these documents, and no wonder it’s difficult to spread information with them.

But do you know what kind of information does spread? Stories. Humans have been spreading information with stories since… well, for a very long time. And what is a use case but a story? It’s a story about how one user is going to accomplish one thing using our system. The story can be as formal or as informal as necessary.

An essential element of a story is a central character - a protagonist. Without a character, a story is just a set of disjointed facts - much like a traditional requirements specification. In a use case, the central character is the primary actor.

Characters make the story readable and actors make our requirements comprehensible. They indicate why a requirement exists (because the actor needs to get something done). They give us clues about what requirements we might have missed (are there stories we forgot to tell?)

And most importantly, actors are what separate the use case approach from traditional forms of requirements gathering.

People new to use cases are often unsure of where to start gathering requirements. I suggest creating a context diagram. A context diagram is a high-level, informal view of three things:

1. the system you're going to be gathering requirements for,
2. the things that need to interact with the system (use case experts call these things external entities), and
3. a brief note about the interaction between each thing and the system (#3 is optional).

Because it's an overview and lacks much detail, this diagram is an easy way to start building momentum in your requirements gathering process.

Create a context diagram by drawing a circle in the center of the page. If your system has a name, use it to label the circle. If it doesn't have a name yet, just label the circle as "System." Then list each of the external entities around your system and draw a line between the entity and the system. If it's not obvious why an entity belongs on the diagram, make a note about the interaction between the system and the entity. Specifically, note what information is passed and who it is passing it (the system or the entity).

Below is a context diagram example for a fictitious website named RentLenses.com. This website allows photography enthusiasts to rent expensive camera lenses by the week.

A context diagram looks so simple that you might be tempted to just skip it. But because they are so easy to create, I prefer to draw them anyhow. Their simplicity helps spread two important pieces of information early in the project.

The context diagram answers the first and most essential question about your requirements: Who needs to use this system? By calling out the things that are external to the system, we define its boundary and scope. In the example above, we can see that building a credit card processing function is out of scope. Instead, RentLenses.com will use an external payment gateway. Incidentally, the external entities on the context diagram are also the first draft of the system's actors (identifying each actor is the next step in the use case modeling processes).

Equally important are the entities that do not appear on the diagram. The context diagram shows only the entities that will interact with the system in some way (either by passing information to it or by receiving information from it). If an entity does not appear, then building that interaction is out of scope.

With a completed context diagram in hand you can quickly vet the objectives and scope of the project among its stakeholders.