In this chapter:
1.2 Where Do Requirements Fit in the Grand Scheme? 5
1.3 A Few General Principles 6
1.4 A Traditional Requirements Process 7
1.5 Agile Requirements Processes 8
"Would you tell me, please, which way I ought to go from here?"
"That depends a good deal on where you want to get to," said the Cat.
"I don't much care where—" said Alice.
"Then it doesn't matter which way you go," said the Cat.
"—so long as I get somewhere," Alice added as an explanation.
"Oh, you're sure to do that," said the Cat, "if you only walk long enough."
—Alice in Wonderland,
Lewis Carroll
This chapter tells you the bare minimum that you need to know about requirements to understand the rest of the book. It is a synopsis of a much larger version of the chapter that is available for download from the book's associated Web page at http://www.microsoft.com/mspress/companion/9780735623989. (See the Preface for more information.) For convenience, the two are referred to as the synopsis and the full versions. The synopsis concentrates on defining concepts and terminology that are used throughout the book; it sets the scene. The full version goes into a lot more detail (on every topic) and provides justifications and advice—but it is still merely a whirlwind introduction to the subject. Both versions are organized in the same way: opening with some basic definitions and justifications, then describing where requirements fit in the overall process of building a system, and putting forward some principles worth following. Both versions end by describing three overall approaches to requirements, which are: a traditional approach, in which requirements are specified in detail before moving on to the development phases; an extreme approach, which strives to produce software as rapidly as possible at the expense of formality and documentation, and in which requirements are much less prominent; and a compromise incremental approach that specifies some of the requirements up front and some later on. Requirement patterns are equally applicable and equally valuable no matter which approach you take.
A number of good books explain software requirements in general and traditional requirements processes in a lot more detail, present a lot of extra analysis techniques, and cover other requirement-related activities ignored here. Of these, Software Requirements by Karl Wiegers (Microsoft Press, 2003), is my favorite. (Others include Robertson & Robertson, 2006; Davis, 1993; and Leffingwell & Widrig, 2000. See References at the back of this book for details.) This chapter (even the full version) is no substitute for such a book, and the reader is urged to invest in one (or more) of them.
This chapter assumes that you want to define what a new software system is for and what it must do—though it insists neither that you write a requirements specification nor that you include in your project a dedicated "requirements phase" following which the system will be designed and built. A system, as far as this book is concerned, comprises a collection of software components and (optionally) the hardware on which it runs; this book does not regard any of the people who use the system as part of the system itself.
This book makes no assumptions about the manner in which you record requirements. The most straightforward way is to use a word processor. Alternatively, you can use a requirements management tool built especially for the purpose.
At least I have got a grip of the essential facts of the case. I shall enumerate them to you, for nothing clears up a case so much as stating it to another person, and I can hardly expect your cooperation if I do not show you the position from which we start.
—Sherlock Holmes: Silver Blaze,
Arthur Conan Doyle
Let's keep our definition of requirements simple:
The requirements of a system define what it needs to do—but not how.
The requirements define the problem that has to be solved: what the system is for and everything it needs in order to achieve that. They do not define the solution. A requirement is a single, measurable objective that a system must satisfy. The best way to express each requirement is in plain text. A requirements specification for a system is a document stating all its requirements plus any background material needed to make it readable and understandable. It needs to define all the functions and other capabilities that the system must possess.
There's no single "right" level of detail to go into in requirements. Requirements can be specified at various levels of detail. A relatively broad requirement can be broken down into more specific requirements that spell out the implications of the original. It's also possible to write multiple requirements specifications at different levels. Some organizations and experts divide requirements into separate levels as a matter of course, often into "high-level" requirements, which capture the business objectives, and "detailed" requirements, which spell out the functions and other capabilities that the system needs in order to achieve the business objectives. This book does not separate all requirements into levels. However, several of its requirement patterns introduce two (or even three) local levels of their own that show how to break down a specific kind of broad goal into clear requirements that are as detailed as developers need. For example, if our system must satisfy a particular standard (the broad goal), we can specify detailed requirements for what the system must do to achieve that goal. ( What, but not how!)
Requirements define most importantly what the system must do, the activities it must be able to perform. These are called functional requirements. They attract the bulk of the attention, often to the neglect of the other characteristics that the system must possess—called nonfunctional requirements—which cover a wide range of topics from performance to security to standards with which the system must comply.
The process of specifying requirements is that of identifying what a system needs to do. It is performed for every system that's ever built, regardless of whether the requirements are spelled out explicitly. A programmer who decides what's needed and simply goes ahead and codes it performs a lightning-fast requirements specification process along the way, even if requirements exist only as fleeting thoughts before being overtaken by more exciting design brainwaves. I argue that it's advantageous to write down all requirement cogitations so that they can be debated and justified in their own right, independent of the design of the solution. A full-blown requirements definition phase isn't the only way to achieve that.
I have no data yet. It is a capital mistake to theorize before one has data. Insensibly, one begins to twist facts to suit theories, instead of theories to suit facts.
—Sherlock Holmes: A Scandal in Bohemia,
Arthur Conan Doyle
Bringing a new system into being involves a number of stages. Exactly how many stages, what each one entails, and who performs them might vary somewhat, according to your organization's culture, who's available, personal taste, and the methodology you're using (and this book leaves that for you to decide). Still, we do need to differentiate the main activities in building a new system. There are endless ways to break them down and represent them. Figure 1-1 shows a simple version that suits our purposes.
This doesn't assume that you perform the whole of one activity before moving on to the next, so it applies regardless of the methodology that you use. Nor does it mean that you must document every activity: you might just picture a requirement in your mind before designing it, or merely think of a design before coding it. Viewed in this way, methodologies differ mainly in the size of each morsel to which this whole process is applied—from the whole system (the traditional approach) at one end of the spectrum to a convenient unit of coding (extreme programming) at the other. In a compromise third approach (which we'll call incremental), we specify a chunk of requirements before moving on to design, then perform a chunk of design before starting development; we do more design and specify more requirements as and when they're needed. Both of the last two fit in with an agile outlook. For the key activities, the differences between the approaches look conceptually something like Figure 1-2.
The second half of this chapter discusses each of these three approaches in turn. Every approach also involves a degree of rework—an iterative element—as errors are discovered in the development, the design, and the requirements.
Like all other arts, the Science of Deduction and Analysis is one which can only be acquired by long and patient study, nor is life long enough to allow any mortal to attain the highest possible perfection in it.
—Sherlock Holmes: A Study in Scarlet,
Arthur Conan Doyle
This section discusses a few general principles to apply whenever specifying requirements. They will help you deliver good results and can help you decide whether or not to include something. This isn't a systematic set of principles; they're merely a few things that I wish to bring to your attention.
Specify the Problem, Not the Solution. Saying that requirements define "what, but not how" means that it's not the role of requirements to attempt to specify the solution or any part of it. This is an important distinction, and it is a rule not to be broken.
Specify the System, Not the Project. Requirements define what a system needs to do: they are a set of objectives. A project is the mobilizing of a team for a temporary duration to achieve those objectives. Requirements have no place saying how a system's objectives are to be achieved, which means saying nothing about a project to implement a solution (including milestone dates, team size, names of team members, costs, budget and methodologies). Also write every requirements specification to be timeless, to be equally valid for multiple systems that might be built in different ways at different times: the requirements could be put into a drawer and brought out in a year or two, or we might build a replacement system in a few years time.
Separate the Formal and Informal Parts.A requirements specification acts like a contract that defines what the builders or suppliers of a system must deliver. But a mass of contractually binding statements are far from enough for a reader to make proper sense of it: it needs background, context, flow, and structure. None of this extra material is contractually binding. It's invaluable to divide the specification into the binding (formal) and nonbinding (informal) parts. The requirements themselves constitute the formal part of a requirements specification: the official definition of what the system must do. Everything else is informal.
Avoid repetition. Express each item of information only once, as far as is practical. Repetition creates extra work and opens opportunities for inconsistencies.
We choose to specify these things not because they are easy, but because they are hard.
—John F. Kennedy (what he might have said if he'd been a business analyst)
The traditional approach to specifying requirements is to have a distinct requirements phase that delivers a detailed requirements specification before starting to design and build the system. Figure 1-3 sums up the steps in a typical traditional requirements phase. The steps illustrated most prominently are those where the bulk of the work is done. The funny "Gather information" shape signifies that it's not isolated in a single early step, but continues until the final specification is delivered (although with gradually less time devoted to it, signified by the tapering towards the bottom of the shape).
The steps shown in Figure 1-3 are:
Prepare. The analyst must be given an outline of the mission: some kind of statement of the system's objectives, before the requirements process can begin, either by explanation face-to-face or via a short scope document. Also find your feet: familiarize yourself with the environment (and the culture, if you're new to it) and identify all sources of information.
Gather (or "elicit") information. The main sources of information are people, documents, and existing systems. The key to gathering information well is attention to detail. First, find out as much as you can by reading before talking to people. Familiarize yourself with all relevant systems, too. But people are the best source of information on what your new system must do. The full version of this chapter describes the two prime ways of gathering information from people: individual interviews and collaborative sessions.
Write draft requirements specification. Start writing the first draft as early in the process as you can, but not until you have a reasonable picture of the major pieces. That, however, should take very little time: just a day or two. Write the "Context" section first. Then identify the functional areas, which form top level sections of the specification. Organize according to what you need to say. Don't be afraid to reorganize as you go along.
Have specification reviewed. Subject it to serious scrutiny to verify that you've correctly interpreted and represented everything you've been told. There are various ways to review a requirements specification, and these vary in their degrees of formality and thoroughness. The full version of this section discusses two methods for review: the independent approach involves distributing the specification to a number of reviewers and asking for their feedback; the collaborative approach brings a group of reviewers together at the same time to perform a detailed and systematic inspection of the specification.
Revise after review. Work systematically through all the individual comments that you receive, updating the specification as appropriate. Any comment could hint at other matters that have been omitted or need to be changed; be alert to observations that have wider implications. After creating a new version of the specification that takes into account review feedback, either send it out for review again or decide that you're happy with this version and regard it as finished.
Other activities can be performed in parallel with the main requirements activities. Two common activities are writing use cases and developing a prototype.
"You are old, father William," the young man said,
"And your hair has become very white;
And yet you incessantly stand on your head.
Do you think, at your age, it is right?"
—Alice's Adventures in Wonderland,
Lewis Carroll
This section discusses the role of requirements when taking an agile approach to building a system. It is aimed at developers and architects who aren't presented with a requirements specification as their starting point. Adopting an agile outlook isn't all-or-nothing; you can take small steps in that direction, or you can adopt it nearly wholeheartedly. You can do just some parts of a project agilely. You can take a traditional approach to specifying requirements and then perform design and development in an agile manner. In that case, you can use the traditional requirements process described in the previous section, and then take whatever agile approach you wish to the development.
The agile manifesto (which lives at www.agilemanifesto.org) defines an agile outlook as one that values people over processes, software over documentation, collaboration over contracts, and responsiveness over plan. "Software over documentation" is our main guide when deciding how to tackle requirements agilely: we should aim to churn out less documentation. The two approaches that follow concentrate on achieving documentary efficiency while still realizing the value that identifying requirements brings. Let's start with a couple of principles to guide any agile requirements process:
Principle 1: Distinguishing problem from solution is valuable. One way or another, you must decide what a new system must do. You must also decide how it will do it. This principle merely says it's good practice to recognize the what separately from the how and to do it first. It gives you something against which you can later gauge the quality of the solution and to compare the merits of two suggested solutions. It gives you a degree of objectivity that's lacking if everything blurs together.
Principle 2: If you identify a requirement, record it such that someone else can find it. This principle does not, however, say where or in what form a requirement should be recorded.
It sounds incongruous to talk about a "requirements process" in the context of extreme programming (XP), because requirements don't appear in concrete form at all in an extreme extreme programming approach. Still, no system can be built without someone deciding what it needs to do, so the requirements are there somewhere. And they must come about as a result of some process or another, however fleeting and ethereal it is. That's the kind of requirements process we're talking about here—with a view to catching and bottling its results.
Building a new system using extreme programming begins by asking users to write a full set of "user stories." A user story is a short description of something the users want the system to do for them. For user stories to be representative, at least one person from each user area (that is, each "actor") must contribute to them. The end result is user stories for the main user functions of the system. Anyone involved in writing user stories might find the requirement patterns in this book helpful for guidance, for suggestions on topics to cover.
Once a set of user stories has been produced, it is used to plan the order in which they are to be implemented. A user story is assigned to a developer, who then figures out how to implement it (starting by defining a set of tests, which XP calls acceptance tests). Each developer must formulate the requirements they are trying to satisfy, even if they are unaware that's what they are doing, and even if the process is over in a split second and never sees the light of day outside their head. The first step in any development task should be to ask: what am I doing? What problem am I trying to solve? Answer those questions before proceeding, and write the answer down as the beginning of the definition of this task's tests. Write it in the form of a requirement (or more than one requirement). Engage a requirement pattern to help you, if there's a relevant one available. A requirement pattern could lead you to recognize the need for extra requirements, some of which might spawn their own development activities.
There are three ways in which requirement patterns can be used in association with extreme programming:
To suggest user stories and what to say in them (to make them more precise or more like requirements).
To interpret user stories in a more systematic manner, to unearth the actual requirements they allude to, and also to identify extra functionality needed to support a function that implements a user story.
To guide the production of a set of "common requirements" to be applied to all systems in your organization, especially rules for good practices to be followed by all developers.
Only perform requirements work as and when it's needed: just in time. That's the premise behind an incremental approach to it. Do a minimum of requirements work up front, so development can begin as early as possible. There are two things to decide here: how detailed the requirements need to be, and when to specify each piece's requirements. At one end of the scale, a full and detailed requirements specification would be written before starting any design and development work; at the other, individual requirements would be defined as part of a development unit. These two are represented by the traditional and the extreme requirements processes already described. An incremental approach is between these two.
Just as agile development involves incremental additions to the software, agile requirements ought to involve incremental additions—that is, gradual expansion of a single set of requirements. Everyone then has the same picture at all times, and we avoid repetition. The requirements specification, like the software, becomes a living being. What's a suitable process for doing this? In keeping with a lean, agile outlook, let's keep it simple:
Specify requirements up front sufficient to convince the customer that we understand what they want from the system (making sure we capture the business objectives) and to get the customer's approval to proceed.
When developer(s) are ready to begin building a particular area, expand the high-level requirement(s) that apply to that area, and specify detailed requirements for everything the system needs in order to satisfy that high-level requirement.