You are currently browsing the archives for the Use Case tag.

The Baker’s Dozen of Use Cases

February 7th, 2011

Rule 11 – Don’t abuse «include»

A use case contains all the steps (transactions) needed to describe how the actor (our stakeholder) achieves their goal (or doesn’t; depending on the particular conditions of the scenario). Therefore a use case is a stand-alone entity – it encapsulates all the behaviour necessary to describe all the possible scenarios connected to achieving a particular end result. That’s what makes use cases such a powerful analysis tool – they give the system’s requirements context.  Use case are also an extremely useful project management tool. By implementing a single use case you can deliver something complete, and of value, to the customer. The system may do nothing else, but at least the customer can solve one problem with it.

Occasionally, two use cases contain a sequence of transactions common to both sets of scenarios. This sequence may not necessarily occur at the same point in each use case (for example, the beginning) but will always be in the same order.

image

 

UML provides a mechanism for extracting this common information into its own use case. The mechanism is called the «include» relationship. The semantics of the «include» relationship mean that the base use cases are only complete if they fully, and completely, contain the contents of the included use case.

image

Included use cases (if you must use them)

This relationship can sometimes be useful, particularly if a sequence of transactions is repeated many times.

However, misunderstanding of «include» tends to lead to a very common abuse: functional decomposition of use cases.

Many use case modellers use the «include» relationship to split a complex use case into a number of smaller, simpler use cases. This can lead, in extreme cases, to an explosion of use cases, with leaf-node use cases capturing trivial functional requirements (for example “Capture button press”).  

These trivial use cases often have no meaning to stakeholders, who should be focussed on what they want to happen, rather than how it happens.  Also, there is a huge overhead is creating, reviewing and maintaining this vast number of use cases.

I call this approach “Design Cases” to differentiate it from a use case.

 

image

Design cases in action

Rather worryingly, several organisations actively promote Design Cases for requirements analysis.  The appeal is obvious:  functional decomposition is a familiar concept with most developers (and if it isn’t they really shouldn’t be developing software!); and it allows the developer to settle back into the comfortable territory of solving problems (rather than defining them)

Remember, use cases are an analysis tool for understanding the system. A simple, coherent set of use cases, reflecting the usage of the system from the customer’s perspective is far more effective than demonstrating, to the n-th level, how the system will operate. That’s what design verification is for.

My advice is to avoid «include» wherever possible.  Prefer repetition of text within the use case description, over trying to identify and extract commonality.  In this way each use case remains separate and complete; and there is no temptation to fall into the functional decomposition trap.  That way lies madness (or at least analysis paralysis).

 

<<Prev     Next>>

The Baker’s Dozen of Use Cases

January 21st, 2011

Rule 10:  The magical number seven (plus or minus two)

Psychologist George Miller, in his seminal 1956 paper "The Magical Number Seven, Plus or Minus Two: Some Limits on Our Capacity for Processing Information", identified a limit on the capacity of human working memory. He found that adults have the capability to hold between five and nine ‘chunks’ of information at any one time. A ‘chunk’ may be a number, letter, word or some other cohesive set of data.

What has this to do with use cases? One of the primary functions of writing use cases is requirements validation – that is, are we actually building the correct system? The use case model is a technique for presenting the system requirements such that the customer can say either yes, we have a correct understanding of how the system should work; or no, we have misunderstood the system.

When presenting information to our (probably non-technical) customer it makes sense to keep the information content manageable. Try to keep the number of transactions in any one flow (that is, a sequence of use case steps between a trigger event and a conclusion) to between five and nine. This gives your customers the best chance of comprehending what you’re writing.

This means that the use case stops being a list of all the system requirements and becomes a précis of the system requirements. Each transaction may therefore equate to more than one system requirement. In practice this is not as over-simplifying as it sounds: requirements are often ‘clustered’ around elements of data and their production and manipulation – effectively what each use case transaction describes.

The skill in writing good use cases is the ability to précis requirements together to minimise the number of use case steps, without creating simplistic use cases.

The ‘seven, plus or minus two’ rule is not hard and fast; more a guideline. If your description has ten steps, this is not a problem; however, if it has thirty then there’s a chance you’ve over-complicated the step. The same is true at the other limit: three steps is fine; one step means you may have over-simplified and lost detail.

 

<<Prev     Next>>

The Baker’s Dozen of Use Cases

January 14th, 2011

Rule 9 – Build yourself a Data Dictionary

Transactions between the actors and the system typically involve the transfer of data.  This data has to be defined somewhere.  If you’ve built a Domain Model ( see Part 5 – here) most of the data will be identified there; but even then the class diagram is not always the most practical place to capture the sort of information you need to record.

Another way to capture this information is in a Data Dictionary.  A data dictionary defines each piece of data in the system, and attributes about that data.  Typically, a data dictionary holds (but is not limited to) the following:

  • An Identifier.  This is how the data will be referred to.  Remember to use a term that has meaning in the problem domain.
  • Definition.  What does this data represent?  (And remember: a good definition consists of a genus – what type of thing I’m defining – and a description)
  • Units of measure; if applicable
  • Valid range; again, if applicable
  • Resolution.  That is, what’s the smallest difference I can measure?  This can become important if your implementation may use fixed point number schemes (for example).

This information is all vital to the developers who must design and code interfaces, etc. but it also has benefit when writing use case descriptions – it decouples the behaviour of the system from its data.

Just as we should decouple user interface details from the use case description (see Rule 8) so should we decouple the data transactions.  Describing the data requirements of a transaction in the use case description is cumbersome and leads to a potential maintenance problem (what if the resolution of a data item changes?  Or its units of measure?  Ask the team that developed the flight systems software of the Mars Climate Orbiter about getting units of measure confused!)

Data Dictionary

As you define your data dictionary, you can refer to data items (by their name) in the use case text.  Use some typographical convention (I use italics) to identify a data item from the data dictionary; or, you could hyperlink it. 

If the data requirements change you shouldn’t need to change the use case – unless it leads to a change in behaviour.  Similarly, you don’t need to elaborately detail exception flows for invalid data.  The data dictionary defines what is valid; the use case defines what should happen if we receive invalid data.  A simple, clear separation of responsibilities.
 
The Data Dictionary is not a new idea.  Twenty years ago, when I started developing software, a Data Dictionary was always created, and was considered a vital part of the design.  Unfortunately, it seems to have gone out of fashion, or been forgotten, in many software development circles.

 

<<Prev     Next>>

The Baker’s Dozen of Use Cases

November 15th, 2010

RULE 6: If it’s not on the Context or Domain models, you can’t talk about it

(If you haven’t already read it, I’d suggest having a quick look over Part 1 of the Baker’s Dozen to familiarise yourself with the fundamentals of use case descriptions.)

Engineers love to solve problems. It’s what they do. A use case model though is not a design model – it’s an analysis model. Use cases describe what the system should do, and in what order. What use cases shouldn’t do is say how the system should achieve these things. That’s what design is for.

Stopping analysts (particularly if they’re developers) from writing implementation details in the use case descriptions is difficult.   One safe way of doing this is to limit the concepts written in the use case descriptions to only those defined on the Context or Domain models.

Both the Context model and Domain model describe things beyond the scope of software implementation. That is, they describe the problem domain, not the solution (software) domain.

The Context model defines the physical parts of the system – external systems, users, interfaces, communication channels, etc.

The Domain model describes the informational context of the system – what artefacts exist, are produced, are inputs or outputs; and how these elements relate to each other.

(See Rule 4 for more on these models; and more.)

All the data in these two models will exist irrespective of what software solution is developed. If they change then our understanding of the problem has changed.

When reviewing use cases look for concepts that are not defined on the Domain or Context models. These concepts are very likely to be implementation details. Look for items like ‘database’, ‘Hardware Abstraction Layer’, ‘Observer’, ‘RTOS’, etc. These are an indication your requirements are actually describing the solution rather than the problem.




<<Prev     Next>>

The Baker’s Dozen of Use Cases

November 8th, 2010

RULE 5: Focus on goals, not behaviour

There is a subtle distinction between the functional behaviour of the system and the goals of the actors.   This can cause confusion: after all, the functional behaviour of the system must surely be the goal of the actor?
It is very common, then, for engineers to write use cases that define, and then describe, all the functions of the system.  It is very tempting to simply re-organise the software requirements into functional areas, each one becoming a ‘use case’.  Paying lip-service to the ‘rules’ of use case modelling, these functions are organised by an actor that triggers the behaviour.

Use Cases based on functional requirements, rather than Actor goals.

I call these entities Design Cases to distinguish them from use cases; and they can be the first steps on the slippery slope of functional decomposition (see Rule 11 for more on this)

Identifying goals requires a change in mindset for the engineer.  Instead of asking “What functions must the system perform?” and listing the resulting functionality, ask: “If the system provides this result, will this help the actor fulfil one (or more) of their responsibilities”. If the answer to this question is ‘yes’ you’ve probably got a viable use case; if the answer’s ‘no’, or you can’t answer the question then you probably haven’t fully understood your stakeholders or their responsibilities.

In other words, the focus should be on the post-conditions of the use case – the state the system will be in after the use case has completed.  If the post-condition state of the system can provide measurable benefit to the Actor then it is a valid use case.

Let’s take a look at what I consider a better Use Case model:

Organising use cases by Actor Goal

The post-conditions of the use cases (above) relate to the goals of the Actor (in this case an Air-Traffic Control Officer).  We can validate whether the post-conditions will be of value to the Actor.

The (main success) post-condition of Land Aircraft is that one of the ATCO’s list of aircraft (that he is responsible for) is on the ground (safely, we assume!).  At this point the aircraft is no longer the responsibility of the ATCO – one less thing for them to worry about.  I argue that this is a condition that is of benefit to the ATCO.

Similarly with Hand-off Aircraft.  As aircraft reach the limit of the local Air Traffic Control (ATC) centre they are ‘handed-off’ to another ATC centre; often a major routing centre.  The post-condition for the hand-off will be that the departing aircraft will be (safely!) under the control of the other ATC, and removed from the local ATCO’s set of aircraft he is responsible for.

Receive Aircraft is the opposite side of Hand-Off Aircraft.  That is, what happens when the ATCO has an aircraft handed over to them from another ATC region.  At the end of the use case, the ATCO must have complete details and control of the received aircraft.

When an aircraft takes off, the aircraft must be assigned to an ATCO, who is responsible for routing it safely out of the local ATC region.  The post-condition of Take-Off Aircraft must be that the aircraft is assigned to an ATCO and that ATCO has all required details of the aircraft’s journey.

In the last two use cases, the ATCO actually gains work to do (another extra aircraft to monitor).  The requirements of the system must ensure that when the new aircraft is received the transfer is performed as simply, or consistently, or straightforwardly, as possible.  This is the benefit to the Actor.

While one could easily argue this is a simplistic model for Air Traffic Control it demonstrates basing use cases on goals rather than functional behaviours.  Each use case is validated by its post-conditions, rather than its pre-conditions and behaviour.




<<Prev     Next>>

The Baker’s Dozen of Use Cases

October 21st, 2010

RULE 4 : The “Famous Five” of requirements modelling

As I discussed in Rule 1, a common misunderstanding of use cases is that they are the software requirements. Unfortunately, this isn’t the situation. Use cases are merely an analysis tool – albeit a very powerful tool (when used in the right situation).

Use cases are just one technique for understanding and analysing the requirements. In order to fully understand the requirements our use cases are going to need some support. Use cases are just one of my “Famous Five” of requirements analysis models.

The Requirements models are:

  • The Use Case model
  • The System Modes model
  • The Context model
  • The Domain model
  • The Behaviour model

Why five models? Well, each one tells me about a different aspect of the system. No one point of view can tell me everything I need to know in order to ensure my requirements are coherent, consistent and unambiguous.


The Use Case model is focussed on interaction behaviour: the who, how, what and when of interaction between the stakeholders and the system.
Use cases focus on operational scenarios. For some systems (especially a lot of application software) the (transactional) exchange of information between the users, or other direct interactors, and the system forms the bulk of the software functional requirements.
However, many embedded systems are not user-centric, or transactional in their behaviour (for example, a closed-loop control mechanism). Anyone who has attempted use case analysis on such systems tends to find the use case model is non-intuitive to construct; and tends not to yield very much information about the behaviour of the software.

The Use Case Model




The System Modes model defines the temporal behaviour of the system. That is, how the behaviour of the system changes of time, in response to external (and internal) stimuli.
The System Modes model allows the analyst to capture when and how the system functionality is available. The System Modes model is a declarative diagram, showing the behavioural modes of the system (without saying how the behaviour will be enacted) and the signals or events that cause the behaviour to change.
Application software may not be modal: it’s either running or it’s not. Embedded systems tend to have more complex dynamics (I see the system dynamics as one of the big differentiators between embedded software and application software). There are typically states where the system’s primary functionality is available, and other states where it is not. For example, most embedded systems cannot provide their primary functionality when they are starting up, or shutting down, or in a maintenance mode.

The Modes Model




The Context model defines the physical scope of the system: what is part of the system (under your control) and what is external to the system.
When creating requirements it is vital to separate the Problem Domain (the part of the real world where the computer is to exert effects) from the Solution Domain (the computer and its software). In fact, requirements should be describe in terms of the effects the system should exert in the Problem Domain (rather than how it should be designed). In addition there must be specifications for what are called Connecting Domains – that is, how the system’s input/output devices must behave (interface specifications).
The Context model gives a clear visual delineation of the Problem Domain (the environment), the Solution Domain and the Connecting Domains. The software is treated as a single black-box entity. The environment consists of the Direct Interactor stakeholders. Each Stakeholder interacts with the system via one or more interfaces (often called Terminators). For each element on the Context model there should be a set of requirements. In this example I have simulated a Context Model using a SysML Internal Block diagram.

The Context Model




The Domain model focuses on the information (that is, data) in the system and, more importantly, the relationship between the information.
The domain model aids with building a project ‘glossary’. In any project there is a huge amount of tacit information about how the problem domain operates, and the language that is used to describe it.
The focus of the Domain model is understanding the problem and describing it, rather than specifying the problem’s solution. Typically, a form of entity-relationship diagram is used. With UML, a class diagram is used (or a Block Definition Diagram in SysML).
It is tempting for development teams to skip this stage; the argument being “well, everybody knows this!” By actively and coherently modelling this information you may well avoid implicit misunderstandings; that can cost a project dear, if found too late.

The Domain Model




The Behavioural model captures the transformational aspects of the problem. The Behavioural model focuses on sources and sinks of information, and what transformations are performed by the system in between.
Although ultimately all software behaviour comes down to executing imperative code, this should be avoided for requirements analysis. Rather, focus on declarative statements of behaviour and where the data comes from (and goes to) rather than how the algorithms will be implemented.




The great strength of producing multiple models of the same system is that they are self-validating. Building a consistent set of models gives confidence that the analyst has truly understood the problem.
Concepts defined in one model must not conflict with the same concept in another model. For example, stakeholders defined in the Use Case model (its actors) must also appear on the Context model (otherwise, how are they interfacing to the system?!); similarly, the Use Case model should not mention any data or information that is not captured on the Domain model.
As I wrote in Rule 1, systems tend to have a predominant characteristic – that is, they will either be a Modal problem, a Transactional problem, a Flow-of-materials problem or a Data-Driven problem. When you are building your models of the system one or two diagrams will tend to give you more information than any of the others. For example, in a data-driven problem the Domain model will probably give you more information about the behaviour of the system than, say, the Modes model or Use Case model. The table below gives an indication of the relative value of each of the models.

Different models will have different value, depending on the type of problem.





<<Prev     Next>>

A Brief Introduction to Use Cases

July 30th, 2010

Since Jacobson defined use cases back in 1992 they have been subject to a vast range of interpretations.   Alistair Cockburn, author of Writing Effective Use Cases states:

“I have personally encountered over 18 different definitions of use case, given by different, each expert, teachers and consultants”

I am no different: this is my personal interpretation of use case modelling and analysis.  To qualify this statement though, this methodology is based on nearly a decade of requirements definition work on a number high integrity projects, including military and aerospace.   That said, techniques that work in one environment may be less effective in another.  I haven’t been fortunate enough to work in every industry sector.   It may be, then, that you disagree with some of my techniques.  This is fine; I won’t think of you as a bad person.

In a series of articles I will present a set of guidelines, or rules-of-thumb.  Each of the ‘rules’ defines a good practice that I recommend when creating use cases.  Each rule forms a quality control on the requirements analysis process.  Ignoring a rule means there is an(other) opportunity for mistakes to creep into your requirements.

There’s no way I could capture every possible method or practice needed to create, analyse, review and maintain your use cases (well, short of writing a book on the subject).  I have decided to focus on a manageable number.  Ten would have been ideal; but that was too few and left out some important points.  Twelve still fell short, so I decided on a “baker’s dozen” – 13 rules.

To start, though, let’s have a quick review of Use Cases.

A brief overview of use cases

Use cases are a requirements analysis technique based on the conceit that (software) systems exist to fulfil the needs and desires of their stakeholders.  Stakeholders don’t use systems for the sake of it - they want to achieve something with the system that is of worth to them.  That is, the system must do something useful for the stakeholder, and in a fashion they expect or desire.

A use case is partial definition of a system’s behaviour, described in terms of a goal that a stakeholder of the system (called an ‘Actor’) wants to achieve, and how they achieve it.  A use case is described in terms of the interaction between the Actor and the system; specifically, it is defined in terms of the information that is exchanged between the actor and the system.

Fig 1.1 – The Basic Use Case Diagram

It is useful to think of a use case in terms of scenarios.  A scenario is a particular instance of interactions.  A scenario describes one possible way of interacting with the system (whilst trying to achieve that particular goal). When trying to achieve their goal, the Actor may have to make choices.  Also, things have a habit of going wrong.  Each variation is a different scenario.  The use case, therefore, is described by every possible scenario.  Obviously, attempting to document a use case by writing every scenario would be ludicrous for anything but the most trivial system.  The way round this is via a Use Case Description.

A Use Case Description is a structured English definition of all the use case steps.  It can be thought of as a’ blueprint’ for generating use case scenarios.  It should be possible to re-create any scenario from the use case specification.  In its basic form, a use case description is a series of steps showing how information is exchanged between the Actor(s) and the system until the Actor’s goal is met.  This flow is always initiated by an Actor (we don’t really want software doing stuff of its own accord!)  This basic form is called the Basic flow, or Main Success Scenario.  In the Basic flow nothing goes wrong and the Actor does the most normal, obvious things (this is sometimes called the “Sunny Day” scenario!)

However, when the Actor must make a choice, the use case description must fork – one path for each option the Actor can make.  Each of these descriptions is described in an Optional flow (sometimes called a Sub flow).

Similarly, not everything always goes right.  If something can go wrong in a scenario, chances are it will at some point (probably when the Actor least expects or wants it to!).  Typically, these conditions are not resolved by giving the Actor an option; they happen beyond the Actor’s control.  We have to record what happens when that ‘something’ goes wrong.  These descriptions are called the Exceptional flows.

Another very useful way of looking at a use case specification is in terms of its start and end conditions.  We can record all the possible start conditions that the system could be in; similarly, we can identify what state we expect the world to be in after we’ve finished.  The use case steps, then, map the initial conditions to the appropriate final conditions.

Finally, we throw in constraints.  A constraint is a requirement on not what the system does, but how it does it.  A constraint may define a performance requirement, a reliability requirement, a safety requirement, etc.  Each step in the use case specification can have one or more constraints applied to it.  It is difficult to document how the constraint manifests itself in the use case but it is easier to document what happens when a constraint is not met.  In this case the failure is treated as an exceptional condition.



<<Prev     Next>>

%d bloggers like this: