Use cases and templates go together like peanut butter and jelly. No other analysis technique has become so associated with templates. Search the web and you’ll find dozens. Just don’t become a template zombie.

When you find a project team that is focused on producing a standard document rather than on considering the content of that document, then you are in the land of the template zombies.

Adrenaline Junkies and Template Zombies

Benefits and Dangers of Templates

Templates are like checklists. They help ensure you haven’t missed anything. Write something into each field of the template and all your bases are covered. Nothing missed.

The template’s comfortable consistency hides the danger: filling out the template gives a false sense of security. Each project is slightly different, but a template remains the same. We’re fooled into thinking that consistency means quality. When in fact, applying a use case template without thinking introduces its own set of problems. It compels use case writers to:

• Include something that wasn’t needed just to fill in a section, making the requirements more difficult to read.
• Skip an important piece of information because it wasn’t in the template (or throw up their hands and claim that use cases “don’t work”).
• Force traditional declarative requirements into a use case format because they didn’t understand what a use case is.
• Get hung up on form rather than content.

Use cases are not about changing the format of requirements – they are about changing the perspective. Rather than look inside-out (“What are all the the things the system must do?”), we look outside-in (“Who needs to use this system? Why do they need to? How will they use it?”). This results in better requirements that are easier to read, and ultimately, better systems.

The World’s Best Use Case Template

There isn’t one. Being successful with use cases doesn’t mean finding the perfect  template. So stop searching. Don’t be a template zombie. The best use case template is one that you aren’t afraid to change to best fit the situation.

By the time you write your first complete use case, you’ll realize you’re going to have more extensions than use cases. Extensions are the primary way that use cases help us uncover the most important, interesting requirements that we might otherwise miss. So let’s talk about how to write a good use case extension.

First Comes the Main Success Scenario

To understand what an extension is, you must first understand the main success scenario. Of all the parts that make up a use case, the main success scenario is the most central. It describes the interaction between the actor and the system as the actor completes the use case. Here’s a main success scenario for a use case named Create Account:

1. System prompts Unregistered User for new account information:
       Full name
       Username
       Password
       Email address
2. Unregistered User enters new account information.
3. System validates new account information
4. System sends account verification code to Unregistered User’s email
5. System prompts Unregistered User for verification code
6. Unregistered User enters verification code
7. System creates account

It’s called the main success scenario because it describes what happens when everything goes right. Of course, rarely does everything go right, but don’t worry about that just yet. Incidentally, if there is more than one way for a use case to go right, pick the simplest way and make that the main success scenario.

We start with the main success scenario because it’s the shortest path between zero knowledge and understanding what a use case is about. Our readers need this base understanding before they can go any further.

Then Come the Extensions

We still need to describe how the system should respond when things either do not go right or do go right, but not in the way we described in the main success scenario. We call these situations extensions. There are two varieties: exceptions and alternates. Exceptions are failure conditions (something went wrong). Alternates are simply a different way for things to go right. We treat them the same, so I’m not sure why I just bothered to explain the difference.

To create an extension, we need three pieces of information:

• The condition that caused the extension to happen
• The steps that will happen when the above condition is true
• What happens when the steps are complete

The Extension Condition

First, write the condition. Alistair Cockburn identifies two essential traits for the condition: It must be something that the system can detect and it must be something the system will handle. Why? If we don’t limit ourselves to the conditions the system can detect, the possible conditions are endless. And if the system can’t detect a condition, we can’t do anything about it anyhow. So there’s no point in adding it to our requirements.

For example, in step 3 of the Create Account use case, username is already in use and email address is already in use are conditions the system can detect. In fact, since we’d handle both of these conditions in the same way, it will be more effective to collapse them into a single condition: username or email address is already in use.

While conditions like Unregistered User mistyped email address or Unregistered User enters someone else’s email address seem valid at first, it’s not something the system can actually detect (How do we know what the user’s email address is?). Now, if either of these things actually happened, the person who incorrectly received the email might choose to NOT verify the account in step 6. That’s something we can detect, and it’s a condition we’d want to handle.

The Extension Steps and Ending

Next, write the steps that describe what will happen when the condition is true. These are just like any other steps in a use case – they explain the interaction between the actor and the system. For example:

3.a. Username or email address is already in use.

1. System displays an error message
2. The use case continues at step 1

Finally, you might need to write what happens when the extension is complete. I have done this in step 2, above. After the extension, the use case might end, it might pick up right where it left off, or it might continue at another step. If what’s going to happen is obvious, you might choose not to explicitly say so – in the name of simplicity and brevity.

As I said earlier, you’ll quickly find that extensions will outnumber use cases. To find them, consider each step of a use case and brainstorm for the things that could go wrong or vary. Throw out the conditions you can’t detect or handle; combine the conditions that will be handled identically. Then describe how your system should handle them. You’re now prepared to uncover and handle requirements you might have otherwise missed.

People have differing opinions about the role use cases play in the requirements process.

Some people think use cases are just one step in the process – something to start with. Others think that use cases bridge the gap between high-level business needs and functional requirements. Others think that use cases show how functional requirements get realized.

In my view, use cases are the center of the requirements universe.

Of course, I’m not saying use cases are the only kind of requirement. There are other categories:

• Declarative Based. The traditional way to define requirements. These assert conditions that the system must adhere to.
• Model Based. These describe requirements using models that describe behavior (e.g. activity diagram) or structure (e.g. a data dictionary).
• Prototype Based. These describe requirements using a representation of the user interface.
• Testing Based. Test cases are another way to state the observable behavior the system must adhere to.

But at the center of these are the Use Case Based requirements. Each use case is based on a goal of an actor using the system. All other kinds of requirements should relate in some way back to one of those goals. Without the goal, there’s no need for the requirement to exist. So, in essence, use cases really are the center of the requirements universe.

What do you think?

When writing requirements, how much consideration do you give to the reader?

Laura Brandau recently commented that high quality requirements are consumable.

Do you think about who needs to consume your requirements and why? Requirements that are hard to consume are ineffective. A complete and accurate requirements specification that nobody reads might as well be incomplete and inaccurate.

Communication not Documentation

The point of writing requirements down is to communicate - not just document. When creating a design or writing a piece of code, a developer needs to be able to understand which of the requirements are relevant to the task at hand. The same can be said of a quality analyst devising a test scenario or a business stakeholder reviewing your spec. These people, like most of us, can only keep about seven pieces of information in their heads at any given time. If your document fails to communicate what the reader needs to know at the time they need to know it, you've lost.

Use Cases: Consumable Requirements

Use cases go a long way towards making a large body of requirements more consumable. Yes, it's possible to write use cases that are hard to read - I know because I've done it myself. But ultimately, a use case describes how an actor goes about achieving just one goal using your system, and it does it in less than ten steps. The relevant non-behavioral requirements are captured while writing the use case and kept nearby. That way, a reader can understand those requirements in the proper context.

All of this leads to better communication, not just more documentation.

What do you think? Are use cases really more consumable?

I was recently interviewed by Larry Clarkin, co-host of The Thirsty Developer podcast. The interview was dedicated to the topic of use cases (big surpise!). We spent our time answering use case-related questions like:

• What are use cases?
• Why are they different or better than other forms of requirements?
• Are use cases different than user stories?
• What are the downfalls and pitfalls of use cases?
• Do use cases have smells?
• Can there be too many use cases?

It was a lot of fun doing the interview. I hope you'll listen in.

You can download and listen to the show here:

http://shows.thirstydeveloper.com/TD046.mp3

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