Ultimately, systems are built to satisfy people’s needs – for more efficient work, for faster travel, for easier home life, and so on. The people building the systems are in general not the people experiencing the need: there is therefore a communications gap between feeling a problem and developing a solution.

With small systems, this gap can be crossed quite readily, as the developers can discuss what is wanted with the users, and prototypes and early working versions can be examined and upgraded quickly.

With larger systems, such an informal approach often does not work, and all too many projects fail to deliver acceptable products on time and to budget. Numerous developers may be scattered over several sites; they may work for different companies, and are probably divided from the users by several layers of contract and subcontract, with little or no opportunity for direct communication.

The requirements clearly need to be documented so as to communicate the various viewpoints of the different kinds of user, the nature of the problem, and the shape of any acceptable solution. Conventional requirements documents typically contain either a large quantity of dataflow diagrams, which users often find forbidding and incomprehensible; or a large number of formally-written statements like ‘The system shall enable the operator to select a contiguous portion of a document’. Readers often find these boring and may fail to see their relevance. Worse, in practice, any document made of many similar-sounding sentences is incomprehensible, as mistakes and omissions are hard to detect amidst the verbiage (‘select an x’, ‘edit an x’, ‘delete an x’, ‘select a y’, etc).

What we want, therefore, is a way of describing what users want, and then what systems should do to satisfy those needs. Both users and developers must be able to understand the descriptions quickly and easily. The requirements need to be in the users’ language, but in a structure precise enough to guide development accurately. Then we have a chance to agree the requirements properly, because everyone knows what they mean.

The Unified Modeling Language, UML, is a large and complex standard, allowing different kinds of people to build a wide range of system and software models ranging from high-level descriptions of business processes to precise definitions of the structure and behaviour of software.

Fortunately, you don’t have to know all about everything in UML to start using it for requirements. The construct that is most often used to hold requirements in UML is the Use Case. System specifications based on Use Case-modelled requirements often include other UML constructs including Activity and Sequence diagrams. We’ll say more on these later, and get started with Use Cases.

A Use Case is essentially a properly-documented chunk of a process. It should have a single goal, and a basic scenario (a sequence of steps or activities) that someone can carry out to achieve the goal. Since life is never simple, there are always other ways of doing things, and things can go wrong, so a use case is not complete without a list of alternative paths and exceptions. If these are complicated, it is wise to make them into use cases in their own right, and to include them in – or otherwise attach them as extensions to – the parent use case.

The use case notation was invented by Ivar Jacobson to describe how different actors interacted with and used some part of a large (existing) system, which explains why process chunks are known as Use Cases. However, the terminology is retained even when the cases are actually about the workings of a business, rather than of a hardware or software system. In other words, the approach works equally well whether you want to describe a problem in the user domain, or the behaviour of a system that helps to solve such a problem. But it is definitely best to focus on one or the other at a time.

For the sake of example, suppose we are a household security company selling locks and bolts, wanting to get into the new and more profitable business of burglar alarms. Our business plan is to sell household alarms, and to make ourselves a steady income by servicing these regularly, as well as by monitoring the households centrally and calling out a guard when necessary.

We can begin by identifying the main actors involved. A Householder will buy one of our alarms to protect her house or apartment. The Householder uses the alarm each normal day to guard against possible burglary. A Maintenance Engineer visits once a year to service the alarm. And so on. In UML, each Actor is represented by default as a stick-man icon, whether the actor is a human or an active system (though we can customise this if we aren’t satisfied with it). Each Use Case is represented as an elliptical bubble.

In the burglar alarm example, servicing the alarm contributes to the overall goal of protecting the householder’s house, as an unserviced alarm may well fail. So, we can add an arrow to show that the ‘Protect House’ use case includes ‘Service the Alarm’. It also includes the ‘Normal Day’ use of the alarm by the householder.

As we think through the business and the use of the system – for instance, in a workshop facilitated by an experienced requirements engineer – we can add more cases at both high and more detailed levels. It is convenient to show the high level cases on the left, and successively lower-level cases towards the right. For example, the primary job of the alarm is to detect intrusion; it is up to the operator in the company’s call center to handle it appropriately. Both cases are ultimately part of ‘Protect House’.

With a tool, we can add this extra detail, and then hide or show it as necessary. We can also choose which types of information to show – e.g., do we want to see all the actors, or only the primary actor for each Use Case? Here, for example, is a diagram summarising all the actors involved in the normal use of the burglar alarm; other cases, such as breakdown and power failure, can be dealt with on other diagrams.

Consider the Use Case ‘Replace Circuit Board’. Should we be including it at this stage? It is certainly something that a Maintenance Engineer might do in the course of servicing an alarm. But if we are thinking about high-level cases like protecting a house and the business of servicing alarms as a whole, it is clearly a minor detail. We can follow the Use Case guru Alistair Cockburn and cut short the ‘diving down a hole’ behaviour that often troubles requirement discussions, by drawing a simple and even humorous icon to indicate the level of the use case. ‘Replace Circuit Board’ is well below the surface for our purposes (though highly relevant when we come to consider the details), so we can draw a swimming fish icon. It is also looking inside the burglar alarm system (how do you know it is made of circuit boards?), so we can show it as a white-box use case. Once you have marked up a use case as being low-level like this, everyone will smile and turn their attention to the real business, which is to identify and describe all the major cases first.

Use Cases divide up the problem into bite-sized chunks which everybody can understand, especially those people who are experts in the domain (burglar alarms) but who may not be expert in requirements engineering. Because the use case stories are easy to follow, they are more likely than conventional requirements to be checked carefully before development begins. This cuts down the risk of building the wrong system, and the embarrassment and cost of having a subcontractor come back to you having discovered deficiencies in your requirements. Equally, the subcontractor benefits from the confidence that the requirements are well understood.

Use Cases are also a practical preparation for development, as UML is becoming the dominant approach for system analysis and design. In such a development project, tools such as Tau permit rapid navigation between use cases and associated specification and design diagrams. The tool can check that definitions are consistent, and by switching between different models you can quickly build up an understanding of the system.

In short, Use Cases are a great navigational aid in a complex project, acting as index headings for the more design-oriented information. Handling requirements as Use Cases ensures a smooth and easy transition from problem to solution.

People often follow up on detailed system use cases (ones that go into what different parts of a system do in turn to satisfy a need) by drawing UML sequence diagrams with a ‘swimlane’ for each type of person or subsystem playing a role in the use case. This helps in the transition from specification to design, as the actors are natural candidates for design objects.

Activity diagrams are essentially traditional flow diagrams drawn in UML style showing activities, decision points, and concurrency. The activities on a flowchart are presumably always carried out by actors. The activities should correspond to steps or tasks in a use case, and the actors should already exist in the use case model, so a tool can check the consistency of the different models and facilitate refinement as necessary.

Another representation useful in system specification is the Sequence diagram. At its simplest, this is like a plan of a swimming pool with a lane for each actor. Time is shown along the lanes, normally downwards on the diagram. Concurrency appears quite naturally as parallel sequences.

Where the logic is complicated, it can be helpful to overlay an Activity chart on top of a Sequence diagram background. As before, each actor has a swimlane and carries out activities, but these can include making decisions (shown as diamonds). Concurrency can then be explicitly indicated with fork and (re-)join symbols, which in UML are bold horizontal bars. For simple cases like the example above, the basic Sequence swimlanes diagram is better on its own. As with Use Cases, the way to decide is just to ask ‘How would this be clearest?’. It’s also important to remember that no diagram can show everything.

The swimlanes approach leads directly to thinking about design – how does the call center supply a schedule to the maintenance engineer? Should the schedule be a design object? Does the engineer have a computer with a radio modem? These ‘how?’ questions move attention on from requirements to design. Conversely, ‘why?’ questions focus attention on essential requirements issues: why does the engineer have to read a schedule? How much of it must the engineer see? Making a satisfactory specification depends on being able to move freely in both directions, checking out questions of practicality as well as of the users’ wants and needs.

Tools which allow easy navigation forwards and back between different models – say, Use Cases and Sequence Diagrams – can greatly speed and simplify the development process, as well as helping to give the users more precisely what they want. No-one ever came up with a quality product straight off: there is a vital iteration and set of trade-offs between what people want, what can be built, and what can be afforded. From an engineer’s point of view, this is between the requirements, system specification, and design. From a manager’s point of view, the trade-off is between quality, cost, and timescale. Either way, Use Cases are a firm foundation for reasoning about development.

All this is very nice and simple, but how does it help you organise your requirements? Alistair Cockburn argues that Use Cases are fundamentally a textual form:

The Use Case diagram is, in short, a helpful summary list that shows the names of the use cases, their relationships and their actors: but it provides practically no detail on what each case consists of, beyond its goal (named in the title) and perhaps its main exceptions (if these are dealt with as separate use cases). In many systems, for instance, it is crucial that the designers know exactly what triggers each use case; this must be written down in the requirements.

There is no agreed standard for documenting use cases, but Cockburn, along with other authors such as Derek Coleman of Hewlett-Packard, have proposed templates for the purpose. The clear need is to describe the various paths of action as story-like scenarios, together with the circumstances in which they apply. These must be in a style that is clear both to engineers and to users of various kinds. Therefore the requirements must be written simply and without confusing detail.

Here then is a complete example Use Case for our burglar alarm, documented in full as suggested by Cockburn. It is a business use case as it describes the operation of the alarm company, rather than the mechanism of a system. It is white-box as it peeks inside the business. It is at high level because it avoids details like how the operator punches the keys to update a schedule. It is not particularly long; some examples in Cockburn’s book run to several pages. Make your requirements as short as they can be, without being so terse that people misunderstand them.

We certainly don’t claim to be perfect at writing use cases; no doubt you can improve on this one. But it is simple and clear, and the headings force the writer to think – just a minute, what exceptions could there possibly be in this case? What triggers this case? Under what conditions can it start? Who has a stake in this, and what do they want? How will we know when the case has completed successfully? These are valuable questions, and they concentrate the mind wonderfully.

On a small and simple project, you may be able to document the use cases as just described using ordinary office tools. Word is fine if all you are doing is writing a specification with a hierarchy of headings and attaching it to a contract, and you can knock up the diagrams using a box-and-arrows graphics tool such as Visio.

But if your project is at all large, you will have to divide it into stages, and allocate the use cases to different developers or subcontractors; and you will need some at once, and some later. A requirements management tool is very helpful for controlling such a project. It can among other things:

• Maintain traces between requirements and corresponding system specifications
• Maintain traces between requirements and acceptance tests
• Calculate metrics to indicate progress, and to highlight areas that need attention
• Automatically draw up-to-date diagrams (such as use case summaries), guaranteed to be consistent with the requirements database
• Automatically summarise the relationships of the use cases and actors
• Display tables of use cases to show status, scope, level, progress, and other attributes.

These are quite powerful advantages. In addition, if you – or your development contractors – are using tools such as Telelogic Tau to design the software, then you can benefit from automatic traceability and navigation between requirements, system specification, design, and test. Good requirements tools such as DOORS provide interfaces to many design, test, and project management tools, as well as application programming interfaces to allow new connections to be created readily.

Here, for example, are some metrics calculated by a DXL (DOORS eXtension Language) script for the current state of the burglar alarm project.

Requirements in UML are clearer, easier to understand, simpler to assess, and offer better possibilities for control than old-fashioned specifications. Contrary to popular belief, they are neither arcane nor meant only for object-oriented software. They consist mainly of structured text, summarised by simple diagrams. Their sharp structure enables projects to be monitored using simple but informative use case metrics.

UML Use Cases allow you to visualise your requirements quickly and effectively. The resulting specifications remain mainly in plain English text, but are well-organised and can be understood immediately by both domain experts and engineers. UML Use Cases can be managed using ordinary office tools, but large and critical projects will certainly benefit from using professional requirements management and modelling tools such as DOORS and Tau.