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.

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.

Russell, a business analyst with a major logistics services company, has great things to say about using CaseComplete to elicit requirements and generate project documentation:

... Try CaseComplete by Serlio. This tool is very intuitive, inexpensive, and flexible. It outputs your requirements in Word format, but handles all the format olympics required as requirements evolve. You can use it to maintain your business models, capture rationale for requirements, use it for the basis of testing and training. Even if you migrate to enterprise tools later, you can use this for the elicitation and documentation process, then upload the requirements.

We've used this on projects of all sizes very successfully. In some projects the developers have taken our model to build upon developing their SRS documents in Case Complete. This saves them a great deal of time and creates a common format between us.

You can download a 30 day trial.

I highly recommend this tool.

Thanks, Russell!

Are you using CaseComplete in an interesting or unique way? Let us know.

So why should you write use cases anyhow? Why are they any better than other ways of specifying requirements?

There are many reasons, but two are key: First, use cases guide us toward the more important requirements and second, use cases are more easily understood.

Traditional ways of gathering requirements involve answering the question of what:

What does this system need to do?

While this seems like a reasonable question,  the answer is a typically a long list of shalls lacking much context. For example:

• The system shall route emergency vehicles with high priority.
• The system shall have the capability to perform remote data protection.
• The system shall log all security events.

Lists like these are accurate, but deceptively problematic. Once the list has more than a dozen-or-so items, it becomes difficult to think about how the items relate. On its own, the list gives us little clue as to when the requirements apply. This makes it harder to figure out how these requirements should be designed and tested. Since the list doesn't indicate who each requirement is written for, it's not obvious if we missed any.

Use cases, on the other hand, involve answering the questions of who, why, and how:

• Who needs to use this system?
• Why do they need to use it?
• How will they use it?

The use case-approach is unique in that it is driven by who will use the system. By starting with who will use the system (the actors) and why they will use it (their goals) we're led to towards requirements that are important to the the people who will actually use the system. We can look at the list of goals we've identified for an actor and readily see if we missed any.

Unlike requirements, use cases are not lists. They are stories. A single use case tells the story of how an actor will use the system to achieve one of their goals. And a collection of short stories are easier to understand than a long list of shalls.