Use Case Formats [ADO04]
Use cases differ from project to project and person to person. A use case that works in one situation may be totally
unsuited for another. Different projects have different needs. Some need rigorous documentation including High
Ceremony Use Cases, which are formal, highly structured use cases. If the writers used a template, then they
filled out all, or almost all of its fields for each use case. High-Ceremony Use Cases are best suited for large,
extremely complex, safety-critical systems, such as flight control systems, telephone switches, etc. They are also used
in development cultures that have high documentation standards. Other projects may be more agile and less formal,
benefiting from Low Ceremony Use Cases, which are informal, less rigidly structured Use Cases. If the
writers used a template, then they may have left many of its fields blank. Low-Ceremony Use Cases are best suited for
smaller, simpler, less safety critical systems where most of the stakeholders have a strong background in the problem
domain. Sometimes, simple descriptions like use case Briefs suffice.
As described in Guideline: Detail Use Cases and Scenarios, it makes sense to write use cases
iteratively. Starting with the basic details, one can then identify the various alternative and error paths the use
case might follow, evaluate, rearrange, or eliminate them, then flesh out the details of the surviving courses. A use
case then can advance through the following forms until it reaches the level of detail required for a specific project.
Different formats for use cases are described in the following patterns:
Briefs
|
describes a format for writing summary use cases.
|
Symphonic Score
|
describes a format for writing more formal, "High Ceremony" use cases.
|
Actor-Goal-List
Context
You have identified your actors, and are trying to identify use cases.
Problem
Developing a set of use cases in an ad-hoc manner can lead to unnecessary work, missing features and feature
creep.
Weight is one of the most important factors in space flight, so important that NASA will not allow anything on a
spacecraft that isn’t absolutely critical to the flight. If something literally isn’t worth its weight, then it doesn’t
go.
Likewise, each use case adds cost to a system, and we want to be sure to include only those use cases that provide us
with some value in our collection.
Forces
Simply listing actors or listing goals is not informative enough, but actors and goals together are
informative. The classical approach to writing use cases is to define a list of actors, then find use cases for
each. A variation on this theme is to itemize the goals the system must accomplish. But neither approach is adequate by
itself. We need to know both who is using the system and why they are using it. Otherwise, we introduce the potential
of either feature creep or missed features. At the very least, a set of use cases should describe this association.
A quick overview of the entire project structure is sufficient and necessary early in the Use Case development
cycle. Ideally, this overview should be as short as reasonably possible. It must contain key information as to who
requires each service, and why they need it. Most other information is not very useful at this stage of the project,
and runs the risk of quickly becoming obsolete, as well as discouraging out-of-the-box thinking. An overview helps the
writers to work through the entire set from a high level view, expanding some use cases, eliminating others, and
combining still others into a more logical grouping.
We need to be able to expand each to a full use case on demand. A “seedling” use case forms the basis for a
full use case later in the iterative development cycle. Each seedling use case needs to convey enough information, so
that someone, possibly other than the outline writer, can easily go back and expand it into a more informative use
case.
Solution
Therefore,
Build a list of actors and their goals as an overview of entire project needs.
Start by identifying the list of actors who will use the system, and identify at least one goal for each. Actors
without goals indicate that you haven’t adequately defined the system. The actor is beyond the system’s scope, doesn’t
belong in the system, or is part of another actor. Likewise, leftover goals can indicate that the system is too complex
and is trying to accomplish too much, or that you haven’t adequately defined all of the necessary actors.
Carefully evaluate the leftovers to see if you are just overlooking some detail, or if they don’t belong within the
system. Remove unassociated actors and goals from the list.
Sometimes, this list may provide enough information to serve as use cases for very small, highly communicating, low
ceremony project teams. Usually, the actor goal list is the first step of identifying use cases.
Briefs
Context
You have written an Actor-Goal-List outlining your use cases.
Problem
Relying solely on an overview to capture the important parts of a system’s behavior is dangerous, because it
provides only high-level information, and can easily introduce ambiguity into a system.
Forces
Although valuable, an Actor-Goal-List does not clearly describe a system. Usually, an outline doesn’t provide
enough precision to avoid ambiguity, which can wreak havoc on a project by leading to unnecessary or erroneous
development. Yet, an outline is helpful because we still want an overview that we can easily scan. Unfortunately, due
to the passing of time or sheer volume of work, it’s too easy to forget what (were once) obvious details.
Iterative use case development requires creating placeholders for expansion. To develop use cases iteratively,
one starts with sparse use cases, reorganizes them, and fleshes them out as the system takes shape. Ideally, these
placeholders should be clear enough to: 1) unambiguously describe their role in the system, and 2) allow someone to
expand the use case, even if they were not involved in the original writing effort.
Because outlines are general by nature, we should not spend a lot of time, energy, or money writing them.
Outlines provide an inexpensive method of documenting complex ideas in a manner that is easy to follow, and provide a
mechanism for people outside of a project to understand its concepts from a high-level. While it may take some effort
to think things through, we don’t want to waste resources describing our ideas. The system at this point is still in a
state of flux, and it is too early to spend much time documenting its shifting details.
Solution
Therefore,
Write two to four sentences per use case, capturing its key activities and key extension handling.
Expand the Actor-Goal-List into “Briefs” by writing a two to four sentence use case
for each entry in the list. Briefly describe each use case’s main scenario and most important extensions.
Include enough information to eliminate ambiguity for at least the main scenario of the system.
Improvisational Score
Context
You are operating in well-known domains or in situations where writing high ceremony use cases would require all of
your allotted development time.
Problem
Writing formal, “High Ceremony” use cases when lesser detail would suffice is wasteful of time and
resources.
Jazz is considered to be “musician’s music”, and jazz players are usually highly skilled. Many jazz musicians prefer to
improvise in small, highly skilled teams - such as jazz quartets. To improvise effectively, the musicians must have a
thorough understanding of the conventions that form the given musical style including chord sequences, rhythmic
patterns, and melodies. These conventions provide a basic framework for the musicians to interact as a team, while
still allowing room for spontaneous creativity.
Likewise, use cases do not always need to be specified in excruciating detail. A far preferable strategy is simply to
define the basic structure of what the developers need to implement. The use cases act as placeholders that may be
fleshed out later or simply improvised by the developer implementing the use case.
Forces
Briefs do not provide enough information. While useful, use case briefs only describe the more significant
parts of behavior. Often, developers need more information, especially when working in unfamiliar domains or in the
heart of the system where the actor has many choices to make and many paths to follow. Briefs do not describe all of
the important events that can happen, nor do they describe the details that go into making choices along the way.
Fully dressed use cases can be too expensive, time consuming, long to write and boring to read. It takes a lot
of time and effort to write a formal, fully descriptive set of use cases. Maintaining this set takes even longer.
Often, a collection of use cases reaches the point of diminishing returns long before it is completely written, much
less formalized. Readers often prefer shorter, simpler use cases over long, complicated ones, as overly detailed use
cases can be overwhelming and, frankly speaking, quite boring.
Many organizations have good group communications to resolve ambiguities on the fly. While briefs may be
insufficient, stakeholders don’t always need everything to be spelled out for them. Developers are usually capable of
asking questions and filling out the necessary detail from their own domain knowledge. Many people can work with a fair
level of ambiguity, and most organizations possess what is often referred to as their “core competencies”. Mature
organizations with strong domain knowledge can survive, and even thrive, using more informal, less precise use cases.
Solution
Therefore,
Specify the use cases to a low level of precision, allowing the developers to fill in the missing details as
necessary. The level of precision required depends on the background experiences of the development team. Skip the less
meaningful fields on the template, and write the Main Scenario in a simple paragraph. Include key extension handling in
the next paragraph or two. Be prepared to resolve ambiguities and expand detail on the fly in the project.
When you can rely upon open and frequent communication amongst the developers and customers, write the use case with
less detail and precision. The developers can fill in the gaps by asking users or by utilizing their domain knowledge.
However, the developers need a thorough understanding of the business context in order to fill out the details for
themselves. Even the most knowledgeable developer will still need access to the customers and users to answer questions
and clarify requirements.
Ideally, the project will be structured to enable effective communication between the customer and the developers.
Typically, this will involve having a small, co-located team, with the developers having easy access to the users
throughout the project. The risk of misunderstanding can be resolved by frequent incremental delivery and the
development organization has a relatively low ceremony culture.
Jazz improvisation does not always work, and can become tedious and unpleasant to listen to, even for the hardened
connoisseur. For this reason, we also need feedback from the audience to determine the success of the improvisations.
Multi-level or “Two-Tier” reviews (see Guideline: Effective Requirement Reviews) are critical to success.
Improvisation may not always be suitable for the organizational culture, and a full Symphonic Score
may be preferable in large, high-ceremony teams. For instance, I once watched a conductor toss his baton away in
disgust when a pianist improvised to such an extent that the orchestra could not follow their score. If the risk of
improvising is deemed unacceptably high then you should specify the use cases with a higher level of detail and
precision. You could start with a strategy of specifying low levels of detail and precision, and then adapt as
necessary.
Symphonic Score
Context
Writing structure for high ceremony situations, such as having many developers, or when development teams are
geographically dispersed.
Problem
Writing “Low Ceremony” use cases for High Ceremony situations raises the risk of miscommunication to
unacceptable levels.
A conductor’s version of a symphonic score contains the music for the entire orchestra as well as any accompanying
vocals. The parts to be performed by different voices or instruments are written on a separate staff, with all the
staves aligned one above another. This score specifies each note, and its associated timing in precise detail, so that
the orchestra can perform a symphony as the composer intended.
As with use cases, a score tells the musician what to play, not how to play it. For most symphonies, the orchestra will
not be able to meet the composer, and instead, they must rely upon the director to interpret.
Forces
Certain development situations and cultures require high degrees of formality. Some organizations operate in a
highly formal manner, and require a highly formal process. While this formality may not be desirable, it is the
company’s way of doing business, so things need to be done that way. Other organizations are highly formal because they
do highly complex, life-critical work, where even small failures could have disastrous consequences. For instance, no
one would feel comfortable flying on an airliner with an off-the-shelf one-size-fits-all flight management system.
The cost of repairing missed communication is high. It is easy to write vague, inadequate use cases full of
ambiguity. Use cases can be too brief and ambiguous, or contain domain specific details which may be beyond the
understanding of many stakeholders. Either way, they provide an opportunity for a misunderstanding that leads to an
incorrect implementation. The cost of correcting these mistakes depends on when they are found. Earlier is cheaper than
later, especially when later means customers finding it in the delivered product. To avoid miscommunication, aim to
write use cases that are general enough for all of the stakeholders to follow, yet precise enough for the developers to
use when building the system.
Developers need detail for implementing steps, business rules, data fields, and especially for handling
extensions. No one has developed a program that can take a set of use cases as input and churn out a completed
system. Even the best case tools seem to require human intervention to flesh out details and resolve ambiguities.
Similarly, developers who do not understand the business context or lack domain expertise may not be able to fully
comprehend a product. In an ideal project, software developers would have access to the domain experts to ask questions
and fill in any areas that may have been missed (see Improvisational Score). But often they do not
ask, so they misunderstand the more complex or ambiguous use cases in the set. To develop a system correctly, a team
needs either access to domain experts, or additional information describing the steps, business rules, data fields and
extension handling that they are implementing.
Solution
Therefore,
Specify your use cases with a high level of precision, explicitly filling in all of the details in the use case
template, while staying technology neutral. The level of precision required depends on the background experiences of
the development team.
Intuition may tell us that if some detail is good, then more must be better. However, be careful about falling into the
trap of over-specifying details. It’s naïve to believe that everyone who reads our use cases will be able to understand
them. Different people may interpret the use cases differently. Prepare for this eventuality in your process, and avoid
the tendency to over specify your use cases. If you try to specify a use case in too much detail you may fall into the
classic analysis paralysis trap.
People are often tempted to address the communication problem by trying to explain the business domain within the use
cases. In a similar manner, they include too much technical detail. Succumbing to these temptations by explaining the
business domain or including technical details is always a mistake, as it complicates the process and obfuscates the
requirements. The reader of the use cases cannot distinguish the real requirements from the boring background
information, and will soon get distracted and lose interest. Instead, include this information in an extra section
adorning the use case.
If you are handing over the requirements to a development team whose members are unfamiliar with the domain then you
will need an alternative strategy for teaching them the domain knowledge.
|