What are Requirements Made of?
Ian Alexander
Article for RQNG
July 2007
In Jonathan Swift’s book Gulliver’s Travels, there were endless arguments between the Big Endians, who thought that boiled eggs should be opened at the big end, and the Little Endians, who thought ... well, work it out for yourself.
Over the years, there have been extensive ‘method wars’ over how requirements should be written. The traditionalists (think of them as Big Endians) argue for Atomic Requirements: indivisible, individually-testable statements, each asking for Exactly One Thing. The modernists (Little Endians) argue for Use Cases. Postmodernists (Extreme Little Endians, probably) argue for User Stories, in other words the briefest of scenarios.
These positions cannot be reconciled directly. Happily, the world (and the range of projects) is wide enough for many ways of doing things. This article, though, suggests that there is a rather different reality from any of the entrenched positions. What is described may seem to you obvious, if you are pragmatic; radical, if you are a passionate Big/Little Endian; or a great relief, if you have felt obliged to pretend to believe in Big/Little Endianism all these years.
My suggestion, then, is that perhaps requirements are not naturally all one kind of thing after all.
Firstly, different means of expression seem to suit different situations.
Sometimes, it really is very convenient to snatch up a pen and scribble some traditional ‘The system shall...’ statements for a contractor. When I hired a builder to do some work in my house, I wrote instructions like ‘Four 13-Amp sockets shall be mounted above the worktop.’ The builder replied by listing the instructions with a more-or-less believable price against each one. If you are building a railway or an aircraft carrier or a football stadium, and you want your subcontractors to do the right thing, you too will find yourself telling them what they have to do in simple, clear, priceable, verifiable shall-statements, before you have had time to think about it.
At other times, it is much nicer to write scenarios, whether as traditional Concepts of Operations, modern Use Cases, or postmodern User Stories – or something pragmatically in between, such as simple lists of steps, maybe with names to make them easier to handle. When I helped a large retail organisation to define what its new software system had to do, I taught the business analysts (all of whom had worked up at the sharp end serving customers themselves, using the creaky old software system) to write use cases. They wrote Preconditions, Primary Scenarios, Exceptions, and Guarantees (also known as Postconditions) like old hands.
So, radically different apparatus can, unsurprisingly, suit different projects. Every sport has its own special equipment. Ping-pong has a little hollow plastic ball and a small flat wooden board with a rubbery surface to bat it with. Tennis has a bigger rubbery ball, and an elongated racquet with strings. Baseball has a hard solid ball, and a wooden club or bat. Can you hit a ping-pong ball with a tennis racquet? Maybe, but it’s hard work, and give pretty poor results. Can you hit a baseball with a tennis racquet? Maybe, but you could break the racquet, and you’d better check your medical insurance too.
Secondly, even the simplest project contains different kinds of information. There may be requirements – things you wish to make true, most likely by paying someone for them. But as well there are assumptions – things you hope are true, because you can’t control them, and you’ll be in trouble if they aren’t true any longer. And there will be issues, and decisions, and definitions, and plans, and .... a whole lot more.
On a development project, there are many different things to represent, and it may be as well to know something about what they are, rather than just pretending they are all ‘requirements’. Here are a few that seem to be useful on most projects.
Please don’t be surprised if some of them are not quite what you expect: there are many ways of being in the world. All projects are different too, just like people.
A stakeholder is a person with a valid interest in a system. Requirements come from people, so it does rather help if you know who those people are. This isn’t just a matter of finding out their names once and forgetting them, either. Good requirements are checked and corrected by stakeholders. Their close involvement helps to keep the project on track.
A definition is a description of a term which your project has decided to use with a special meaning. There aren’t enough words even in a large language like English to distinguish all possible technical meanings. Most likely, in your stakeholders’ domain, there are some ordinary-looking words that mean something special.
That means, by the way, that you can’t rely on your company’s global glossary or jargon-buster, because most of what it contains will be irrelevant to your project, and quite a few terms will be defined wrongly from your project’s unique point of view.
So, you probably need to make your own project dictionary, with your own definitions of your own special terms. These must be consistent with each other; in fact, they should as far as possible be defined in terms of each other, with as few references to the ‘real world’ outside as possible. (You can’t define the real world; trying to do so has caused philosophers endless trouble. The best you can do is to point at it, and hope your readers get a rough idea what you were pointing at.)
A goal is something that a stakeholder wants: in system development, something that the system might ideally deliver to that stakeholder. It may be impossible to achieve, even with unlimited resources: a perfectly safe railway; a perfectly reliable network; instantaneous notification; delighted customers. That is just fine for goals: they don’t have to be realisable, just truthful representations of human hopes and wishes.
Even worse, goals may be individually realisable, but may be in conflict with each other. You can have one or the other, but not both.
Some conflicts can be avoided when technology
improves:
you’d like the device small, light, fast, and cheap: just wait a few
years.
Some conflicts are due to personality clashes:
hire a better facilitator.
Some conflicts are due to misunderstandings:
create
some definitions.
Some conflicts are real:
your project has to live
with them, unless you can persuade some stakeholders to drop conflicted goals.
The project will be driven, powerfully shaped, by the remaining conflicts. It will have to seek acceptable compromises or ‘trade-offs’, possibly ones that have never been attempted before.
This is not some rare and obscure process. The car-maker Volvo, for instance, has a deserved reputation for safety. A Volvo car is a vehicle that trades off as little loss of speed and fuel economy as possible for as much safety as possible. Modern Volvos are remarkably safe: but also remarkably fast and economical. How did the company do that? Not just by writing ‘The car shall...’ lots of times, that is for certain. It was by understanding the goal conflicts, and by exploring the right trade-offs for the kind of car they wanted to produce.
An interface is a defined boundary between your system and other people’s systems. An interface can be of any imaginable kind: a data structure in XML, an oxygen pipe, an electrical connector, the three-dimensional definition of how your engine is to bolt on to their aircraft, anything. By the way, it should be clear that interfaces must be defined in complete design detail, down to bits and bytes (or more likely, down to a reference to the exact section and version of the relevant Standard).
If anyone tells you that design isn’t allowed in requirements, they are well-intentioned (it is certainly a good idea to avoid premature design choices) but confused. Interfaces with existing systems often form much of the functionality of a system, and could be all of it in some cases.
An assumption is something you rely on to be true, but can’t control. This is almost the opposite of a requirement: something that is currently untrue, but you have decided to make true through the work of your project.
Assumptions are dangerous things for a project, especially if they are unstated. Stating an assumption is the first step to mitigating the risk that the assumption may break.
For instance, if you explicitly assume that a particular interface will remain stable for the next 2 years, and it changes, then you know that you will have to change everything that depends on that interface. If you have wisely isolated the software that deals with that interface, at least you know the size of the necessary rework.
Issues and (project) decisions are another pair that were made for each other, like bats and balls, or bread and cheese.
An issue is something unresolved that is holding up the project, because people don’t know which way to go: there may be a choice of rules that could possibly apply, or it isn’t clear which assumption should be made, or whatever. The resolution to an issue is a decision, published to the whole project. Sometimes a decision may affect more than one issue, but the simple approach of having an issues table with a decisions column on the right works pretty well. Each row of the table represents one issue. You can have columns for ID, Issue, Raised By, Date Raised – you know the kind of thing – but the critical bit is the Decision, with its Decided By and Date Decided. If the Issue relates to just some requirements or use cases, you can cross-reference it to them – with hyperlinks or database links or requirements tool traces. Of course cross-referencing applies to all your other requirement components too.
This list could be continued at some length, but this article is quite long already, so I’ll just mention that other kinds of requirement include Qualities (like safety) and Constraints (like the box mustn’t be too heavy for one person to lift).
These have always fitted rather awkwardly into the specifications toolchest. People have given them odd names, like ‘Non-Functional Requirements’: requirements that don’t work, perhaps. Abbreviating them to ‘NFRs’ has only made matters worse: it sounds as if there is a select clique of people who know about these things.
The truth is just that there are a lot of kinds of things that different projects find they need to specify, from resisting electromagnetic interference to battery life to not being too fiddly to use to ability to resist dust, heat, damp, and being dropped onto a concrete floor (and many more like that). These things are not impossible to classify (there’s a free template on my website, http://www.scenarioplus.org.uk) but they are certainly awkward and numerous. The main value of a template is not in dictating how things should be organised, but in reminding you to think about whether your system should have any requirements of some of these kinds. Ultimately it doesn’t matter how you organise your requirements, as long as the structure makes it easy to find errors and omissions.
One thing should be becoming apparent from all of this: much of the information that people used to lump together as “the requirements” isn’t really “requirements” in the narrow sense at all. But in a bigger sense, it all helps to say what you want: defining your terms and assumptions and goals and so on gets you a long way towards communicating your requirements effectively.
But does it get you all the way? Do you still need to write any traditional requirements at all? The world is unhappily split into Big Endians and Little Endians on part of that question, as I mentioned at the start. However, while people who favour writing stories, scenarios, or use cases can justly claim that these approaches are sufficient to define behaviour (ie functionality), it is clear that other kinds of requirement, such as Qualities, Constraints, and Interfaces need to be handled differently.
Each Quality or Constraint (and individual functional Requirement if you are writing those) needs to have its own Acceptance Criteria: each one is unique and has to be measured in its own way. This is in marked contrast to the steps in a Scenario or Use Case, which can all share the same Guarantees or Postconditions.
For example, the constraint ‘The casing shall be finished in grey stove enamel to Std-12345’ has two acceptance criteria: that the finish is grey stove enamel, and that it complies with Std-12345. These can be written as traditional text (as just illustrated), or broken out into separate columns or database fields.
The same sort of thinking applies to other components too. You will probably find you need to track the Priority and Status of your different-kinds-of-requirement as you progress. Even an individually-testable requirement turns out not to be an indivisible atom, but something more like a filing card with multiple fields, a database record, or a software object.
Requirements seem to work much more naturally, more comfortably, if split into different components.
To repeat, not every project needs to deal with every one of these requirement components. Not every sport involves hitting a small hard red ball, just after it has bounced awkwardly on grass, with a flat-faced willow bat.
If you couldn’t help noticing that quite a few of the problems on your current project, or the previous ones, were caused by having to try to force everything into some inadequate little template – in other words, to hit every whizzing ice-hockey puck with a ping-pong bat, because the documentation standards only cover ping-pong – then maybe you will find some of these components useful.
© Ian Alexander 2007
Ian Alexander is an independent consultant and trainer specialising in requirements. He is the lead author of the books Writing Better Requirements (Addison-Wesley 2002) and Scenarios, Stories, Use Cases (Wiley 2004). He has written many research papers and popular articles on requirements. These and various free tools and templates are available from his website http://www.scenarioplus.org.uk