Managing Software Requirements the Agile Way

5 (1 reviews total)
By Fred Heath
    What do you get with a Packt Subscription?

  • Instant access to this title and 7,500+ eBooks & Videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies
  1. Free Chapter
    Chapter 1: The Requirements Domain
About this book

Difficulty in accurately capturing and managing requirements is the most common cause of software project failure. Learning how to analyze and model requirements and produce specifications that are connected to working code is the single most fundamental step that you can take toward project success. This book focuses on a delineated and structured methodology that will help you analyze requirements and write comprehensive, verifiable specifications.

You'll start by learning about the different entities in the requirements domain and how to discover them based on customer input. You’ll then explore tried-and-tested methods such as impact mapping and behavior-driven development (BDD), along with new techniques such as D3 and feature-first development. This book takes you through the process of modeling customer requirements as impact maps and writing them as executable specifications. You’ll also understand how to organize and prioritize project tasks using Agile frameworks, such as Kanban and Scrum, and verify specifications against the delivered code. Finally, you'll see how to start implementing the requirements management methodology in a real-life scenario.

By the end of this book, you'll be able to model and manage requirements to create executable specifications that will help you deliver successful software projects.

Publication date:
August 2020


Chapter 1: The Requirements Domain

Now that we know what this book is about, we can begin our exploration of the requirements domain. A domain is an area of knowledge within which we can operate. As software professionals, we move between different domains daily: the coding domain, the testing domain, as well as client-specific domains such as banking, engineering, education, and so on. In every domain, we deal with specific domain entities that represent items of knowledge or interactions within the domain. In the coding domain, for instance, we deal with entities such as data structures, algorithms, functions, and so on. These entities reflect how we capture and utilize domain knowledge. The aim of this chapter is to introduce you to the requirements domain and its entities.

We will start by explaining the meaning of requirements and specifications, and discussing the requirement life cycle. We will then define the role of stakeholders and actors and talk about the goals they have in relation to our system. Lastly, we will consider the importance of bridging the gap between requirements and specifications and how this book will be approaching this problem. The main sections herein are as follows:

  • The requirements domain
  • Identifying stakeholders
  • Identifying goals
  • Goals, requirements, and specifications: a traveling analogy
  • Crossing from requirements to specifications

By the end of the chapter, you will know the difference between and the importance of requirements and specifications, as well as the stages requirements move through during a project's life cycle. You will also be able to create and validate stakeholder goals, understanding the importance of writing specifications, the pitfalls with current approaches, and how this book will be tackling this subject.


The nature of requirements and specifications

Requirements can arrive at any time in the project life cycle and from a variety of people: directors, CEOs, business owners, business analysts, project managers, product owners, and end users will all at some point require or expect something of the system we are building. Our job as system builders is to analyze, validate, scope, and classify these requirements. We start this process by mapping requirements into a requirements domain model. A domain model is a representation of all the important entities and their relationships within a specific domain.

So, for instance, in the pizza-making domain (one of my favorites), we would expect to find entities such as base, toppings, restaurant, oven, and delivery person, as well as the relationships between them. Knowing what these entities are and how they are connected allows us to create and deliver pizzas. Similarly, in the requirements domain, we'd expect to find entities and relationships that help us define, conceptualize, and deliver requirements. We'll be exploring requirements domain entities and activities throughout this book.

As with every business domain, it is imperative to ensure that the domain entities and terms used herein are clearly defined and understood. After all, ambiguity ruins productivity and one of the goals of this book is to actualize a productive requirements management methodology, so let's start at the beginning…

What is a requirement?

Simply put, a requirement is a stakeholder's expression of a need, wish, or desire with regard to the system being built. Requirements come in different shapes, forms, and sizes, and from various sources. They may be provided verbally, on paper, or as computer files. Requirements may be provided as follows:

  • Formal statements (for example, the system must provide a document searching facility)
  • Business rules (for example, accounts with monthly deposits larger than $1,000 receive 2% higher interest)
  • Examples (for example, Joe didn't have to pay for his coffee because it was his eleventh one in that store)
  • User stories (for example, as a loyalty card holder)
  • Business processes, that is, sets of tasks and activities that are executed in tandem in order to accomplish an organizational goal
  • Screen mock-ups or wireframes
  • Narratives or storyboards
  • Flow-charts, activity charts, or some other type of diagram

Requirements, on their own, are not really useful. In order to be able to implement and deliver requirements, we must give them context and scope and fit them within a user workflow. In other words, we need to turn them into specifications.

What are specifications?

A specification is a description of the system behavior required in order to fulfil or realize a requirement. So, if our requirement states that The system shall provide a document searching facility, a specification should tell us what the system will do to allow the user to search for documents. A specification is just a way of defining how we're going to realize a requirement. Nothing more, nothing less.

Requirements without specifications are pretty useless when it comes to delivering a working system. Unless we analyze and define the impacts (that is, expected behaviors) the requirements have on our system, we stand little chance of building a system that does what its intended users want it to do. Our coding prowess, software engineering skills, and technical expertise stand for nothing unless we can build the right system. To paraphrase an old adage, Most developers know how to build the system correctly. Not many know to build the correct system.

Having specifications is a great start towards building the correct system. Being able to analyze and map the requirements into proper specifications is a major step towards ensuring we will be building the system that our stakeholders need and want.

The requirements life cycle

Requirements management, like many other software engineering disciplines, consists of distinct stages, as illustrated in the following diagram:

Fig. 1.1 – Requirements life cycle stages

Fig. 1.1 – Requirements life cycle stages

Let's take a closer look at what each stage involves:

  • Elicitation: The collection of requirements, which can be done in many different ways.
  • Validation: Ensuring that the requirements fulfill a realistic and useful business need.
  • Modeling: Having a structured and consistent way to describe and store requirements.
  • Specification: This is where we translate the requirements into concrete and clear system behaviors.
  • Documentation: It should go without saying that requirements must be well described, detailed, and documented.
  • Tracing: Knowing which requirements affect system behaviors and which behaviors are necessitated by specific requirements.
  • Classification: Requirements can be classified according to the area of the system they affect, their complexity level, their risk level, and many other factors.
  • Prioritization: This is usually done according to impact and precedence.
  • Verification: Ensuring that our system functions in a way that fulfills the requirements.
  • Change Management: Dealing with changes to requirements.

Any and all of these stages may and do occur repeatedly throughout a software project's life cycle.

This book provides methods and techniques to address all of these stages. However, before we get into them, let's define and understand our requirement domain entities, starting with stakeholders.


Identifying stakeholders

A stakeholder is someone, or something, that derives value, benefits from, or influences our system. There is a stakeholder sub-set we call Actors. These are stakeholders who interact with our system, either directly or indirectly.

All actors are stakeholders, but a stakeholder is not necessarily an actor. This is because there is another sub-set of stakeholders we call non-acting stakeholders. These would usually be people like directors, business owners, enterprise architects, or senior managers. These usually are our business sponsors. They have a stake in the system, and they will probably make decisions that influence the system, but don't expect to see them sitting down in front of a screen and using the system any time soon. The following diagram illustrates the relationship between actors and non-acting stakeholders:

Fig. 1.2 – Stakeholders

Fig. 1.2 – Stakeholders

Actors may be further divided into two categories:

  • Primary actors interact with the system directly through a UI or API in order to achieve a specific goal.
  • Secondary actors are actors that the system needs to be assisted by. This makes it possible to achieve the primary actor's goal.

Secondary actors may or may not have goals that they need to reach by using the system. Primary actors always have a goal that they expect to reach by using the system. Let's take the example of an online loan system. The credit consumer using the system expects to get a loan. The system will provide the loan only if it receives a positive response from a credit reference agency, such as Experian or Equifax. The credit consumer is a primary actor as they interact directly with the system in order to accomplish a specific goal. The credit reference agency is a secondary actor as the system relies on it in order to achieve the primary actor's goal.

Important note

System developers are not actors. Developers are an intrinsic part of the system; they act as system proxies. Actors are always external to the system.

We will be talking more about discovering and defining actors in Chapter 5, Discovering Requirements.


Identifying goals

Our stakeholders will have their own goals and objectives for using or sponsoring the system we are building. Understanding these goals is critical to the successful elicitation, analysis, and modeling of requirements. Stakeholder goals usually fall within two categories, depending on whether the stakeholder is a non-acting stakeholder or an actor. Actors have goals related to the domain in which they operate, for example, retail, education, and banking. Non-acting stakeholders are usually our system's business sponsors, such as directors and executives. As such, their goals are business-related; they mainly sponsor our system because they want to expand or protect their business. Let's look at domain goals first.

Domain goals

Domain goals drive our system actors to use our system in order to increase their value within their domain. For instance, if we're building a learning management system, many of its users would be aspiring to use our system to increase their knowledge or skills. If we're building a marketplace system, most of our users would want to either make money by selling items or to acquire needed items by buying them.

Here are some examples of domain goals:

  • A student wants to get their coursework assessed by a teacher.
  • A teacher wants to pass their knowledge on to a student.
  • A teacher wants to ascertain whether the student has gained adequate knowledge.
  • A seller wants to make a profit on an item they sell.
  • A seller wants to get rid of an unwanted item.

As observed in these examples, an actor may have multiple domain goals. In addition, value may be added to multiple actors via the same goals. For instance, a teacher ascertaining whether the student has gained adequate knowledge benefits both the teacher and the student.

We will be exploring techniques for discovering domain goals in Chapter 5, Discovering Requirements. One thing to keep in mind, however, is that domain goals must always be aligned with business goals. We do not want to allow certain actors to achieve goals that could be detrimental to our business. With that in mind, let's take a closer look at business goals.

Business goals

These are goals that are mainly set by non-acting stakeholders, such as directors, VPs, and senior managers. These people are usually our executive sponsors, meaning that they may approve or support the allocation of resources and they may also champion the project to other members of senior management within the business. They do all that because they have specific goals that they want to accomplish through the adoption and use of our system. As system builders, analyzing these goals and their impact on our system is a crucial step towards defining their requirements.

A business goal's motivation and expected outcome should ultimately fall under one of these categories (see Further reading):

  • Increasing revenue
  • Reducing costs
  • Protecting revenue
  • Avoiding future costs

Any successful business must always be aiming towards generating enough revenue to realize its purpose. Even charities and non-profit organizations must be able to generate adequate revenue if they are to fruitfully continue their charitable or societal work.

A useful technique for determining a business goal's motivation is the five whys technique (see Further reading). If after the five questions the answer is not one of the preceding bullet points, then you should seriously question the value that a goal adds to the business. This helps to avoid and filter out vanity and pet goals, which can derail and jeopardize the project.

Consider the following business goals, where the goal's incentive can be easily discerned using the five whys:

Goal 1: We need to automate user maintenance tasks, such as password resets and account upgrades.

  • Why? So that system users do not have to call the system administrator for routine maintenance.
  • Why? So that administrators do not spend time resetting passwords and upgrading accounts.
  • Why? So that administrators can spend more time monitoring the system and fixing bugs.
  • Why? So that the system becomes more stable and performant.
  • Why? So that we gain more users (increase revenue) and have fewer users leaving us (protect revenue).

Goal 2: I want to reward loyal customers.

  • Why? So that returning customers can feel valued and also save some money.
  • Why? So that customers keep returning more often.
  • Why? So that they spend more money on our products (increase revenue).

Goal 3: We want to receive employee feedback.

  • Why? So that the business can see what we do well and what we do badly.
  • Why? So that the business can fix the bad things and keep doing the good ones.
  • Why? So that our employees are happy working for the business.
  • Why? So that our employees are productive and won't leave the company (avoid future costs).

Good business goals add value for stakeholders by specifying goals tangential or extrinsic to the system's inherent abilities and functionality. For instance, I want customers to buy books is not a valid goal for an online bookstore. For a bookstore, customers buying books is an intrinsic and implied goal. I want customers to buy more books from us than competitor X is better, though it still lacks a strategic aspect. With that in mind, let's take a look at strategic goals.

Strategic goals are the best goals

The best business goals are the ones that are not too abstract, nor too specific; the ones that outline strategy but not tactics. For instance, the goal Reward loyal customers can be framed as Increase sales by rewarding loyal customers. Increase sales is the end goal and rewarding loyal customers is the strategy. If the goal was simply Increase sales or reduce costs then it would ultimately fall to whoever happened to try and accomplish that goal, a business analyst or – shock, horror – a software developer to determine what the best strategy would be. The best people to define the strategy behind the goals are the non-acting stakeholders: the directors, business owners, and senior managers.

On the flipside, should the goal become something like Increase sales by rewarding loyal customers by giving them free gift bags if they spend over $500 in a single transaction, then we are mixing strategy with tactics. This can be a bad thing, as creating tactics requires a level of specific domain, system, and architectural knowledge that is usually lacking in non-acting stakeholders (and I'm saying this in the most respectful way). For example, the director or sales manager specifying the free gift bag ploy may not be aware of any logistics or distribution problems in delivering that many gift bags. Tactics are better developed by a more diverse stakeholder participation and should be captured separately as system capabilities. We will see exactly how to do this in Chapter 2, Impact Mapping and Behavior-Driven Development.

To put this in a military context (since it serves as a good analogy), formulating strategy is the job of the Field Marshals and Joint Chiefs of Staff. They can see the big picture and can come up with plans on how to win the war or the campaign. They create the strategy. Winning battles, on the other hand, is the job of Captains, Platoon Leaders, and other ground commanders. It is unlikely that a Field Marshal will know the specific strengths and capacity of specific platoons or have detailed knowledge of the terrain where a particular battle is to be fought, so as to create the best tactics to win the battle. These are best left to the people who have the most knowledge of such things. In a business domain, the Field Marshals are the senior business people who understand what they need to do to push the business forward. The Captains and Platoon Leaders are the project managers, architects, business analysts, and software engineers who know what to do in order to realize the Field Marshal's strategy.

Case study on lack of strategy

This business goal has a valid and obvious incentive, which is to increase revenue by increasing service contract sales.

Stated goal: We need to increase service contract sales.

So far so good. However, it doesn't outline a strategy for increasing service contract sales. A potential way of achieving that would be to offer the product at a discounted price if the customer also buys a service contract. Another way would be to offer customers a financial rebate if they don't raise any incidents by the end of the service contract. I am sure you can think of many other ways too. So, let's re-write the business goal with that in mind:

Offer financial incentives to customers buying service contracts.

That's better! We outlined the strategy (offer financial incentives) and we left it to the analysts, business managers, and engineers to come up with some tactics for our strategy, such as discounting product prices or offering money rebates. In the requirements domain models, we represent tactics as capabilities, and we will be examining these in detail in Chapter 2, Impact Mapping and Behavior-Driven Development.

Case study on specifying tactics within the goal

In this case, this business goal is about increasing revenue, which is good, but it also dictates a very specific way to achieve it.

Stated goal: Reduce product price by 20% if customer buys a service contract.

The trouble with this is that it constrains and limits our options in discovering any other ways to increase service contract sales. There could be more, and possibly better, ways of selling more service contracts (actually, I am certain there are). However, by sticking with this business goal we will never find out! So, let's re-write this business goal as follows:

Offer financial incentives to customers buying service contracts

This gives us the opportunity to investigate and discover all possible financial incentives we could offer in order to increase service contract sales.

The SMART trap

It is sometimes suggested that business goals follow the SMART criteria:

  • Specific: Target a specific area for improvement.
  • Measurable: Quantify or at least suggest an indicator of progress.
  • Achievable: Ensure goal is attainable and within reach.
  • Realistic: State what results can realistically be achieved, given available resources.
  • Time-related: Specify when the results can be achieved.

I find strict adherence to all these criteria to be dangerous, as often the Measurable and Time-bound or Time-related criteria are too difficult to pin down in any meaningful way, especially at the beginning of a project. Even more importantly, the Measurable and Time-bound criteria can quickly turn into self-fulfilling prophecies, blinkering your organization and turning it into a quantity-driven, rather than quality-driven, business. Unfortunately, some people are unable to manage things they can't measure so they compensate by imposing artificial deadlines and random outputs. This is the kind of thinking that kills projects, as people focus on the numbers instead of the things that really matter, such as the product quality, the actual business strategy, and its clients' needs.

Eric Ries (refer to Further reading) calls out vanity metrics as non-actionable metrics that make some stakeholders feel good about themselves but do not offer any valuable insight or value. Imagine if one of our stakeholders wanted to increase sales by 50% in the next quarter. In this case, we go ahead and implement product features that cause sales to increase by 43%. Technically, we failed. In reality, though, we were a huge success. We added system functionality that caused many more people to buy our product. What if we did not hit the 50% target? Let's face it, the only reason that number existed is that increase sales by 50% looks much better on someone's resume than increase sales by 43%. It would have been much more effective if the goal was set along the lines of Get more people to buy our product by making it easier/faster/prettier. That would have triggered a quality-driven effort for product improvement, rather than just doing what it takes to meet an arbitrary quantity.

Case study on less time on support calls

A well-known computer manufacturer, very popular in the late 1990s, set a customer service business goal to reduce customer response time by 50%. In other words, they wanted their support staff to be able to close a call twice as quickly as before. The support staff reached this goal by speaking very quickly, and sometimes rudely, to their customers, not performing full diagnostics, and even hanging up on callers! The goal was achieved but a large number of consumers stopped buying computers from that company. By focusing on quantitative targets, the company degraded the quality of their service.

Case study on reducing cost, whatever the cost

A company I once worked for set a rather arbitrary but measurable and time-bound goal to reduce software department costs by a certain amount in the next year. When, towards the end of the year, costs had not been reduced by the desired amount, the directors decided to reach their goal by firing their most experienced and skilled engineers. When a new, big, and profitable project arrived some time later, the company didn't have the right staff to deliver the project. The cost-cutting target had been met but the company eventually went under. Being fixated on the metrics of their goal caused the company to make some bad strategic decisions.

Perhaps this was what famous engineer, statistician, professor, and management consultant W. Edwards Deming meant when he said this:

People fixated on meeting their targets will usually do so, even if it means destroying the company.

So, don't get obsessed with SMART goals. Instead, treat strategic business goals with valid motivations as good business goals.


Business goals are validated by ensuring they have the proper financial motivation and that they prescribe a strategy. Business goals that do neither should have their validity questioned.

A good way to understand the relationship between goals, requirements, and specifications is to think about undertaking a gastronomic expedition to a new city. Let's do that next.


A traveling analogy of goals, requirements, and specifications

Here's a thought experiment to help you to visualize the relationship between goals, requirements, and specifications. Imagine, for a moment, that you're a visitor to the great city of Cardiff in Wales, United Kingdom, and you want to sample some of the famous Welsh cakes you have heard so much about – mainly from me! So, you take out your cell phone map app and you search for the nearest Welsh cake bakery. You then ask the app for directions to the bakery. The app gives you a choice of routes dependent on your mode of transportation, the time of the day and the local traffic conditions. You then choose a route and follow it, hoping to sample some local delicacies. Let's relate this to requirements management:

  • Your goal is to eat some Welsh cakes.
  • Getting to the bakery is your requirement.
  • The route you choose to follow is your specification.

It's clear that unless you have the specification (route to bakery), you will never be able to realize your requirement (get to the bakery), and achieve your goal (eat some yummy Welsh cakes!). In much the same way, unless we have a specification, we will never be able to build a system that will help our stakeholders reach their goals.


Crossing from requirements to specifications

Turning requirements into specifications is one of the hardest parts of software engineering and is the part most software engineers get wrong most often. In this section, we'll examine why this is happening and we'll set out the direction we'll be taking in this book in order to provide a safe and solid bridge between requirements and specifications.

Fig. 1.3 – From requirements to specifications

Fig. 1.3 – From requirements to specifications

We will build this bridge using a number of techniques and processes, within the context of a behavior-driven development (BDD) methodology. To understand how we will achieve this we will use a mental model called requirements funneling.

The requirements funnel

As system builders, we get requirements constantly thrown at us and from all directions. Our clients, but also our colleague system builders – whether they are business analysts, developers, project managers, or some other role – discover new needs, wishes, and desires, or sometimes simply change pre-discovered ones. Our job is to successfully translate these needs, wishes, or desires into specifications, either by creating new ones or mapping the requirements to existing ones. It's a bit like having a big funnel into which requirements are thrown in and, by applying certain filtering and analysis techniques, we distil them into a requirements model and subsequently into executable specifications as we can see in the following diagram. We will be talking more about executable specifications in Chapter 3, Writing Fantastic Features:

Fig. 1.4 – The requirements funnel

Fig. 1.4 – The requirements funnel

The filtering and analysis techniques we apply to the requirements, as they come through the funnel, are a structured conversation, business process mapping, and D3. We will examine all these in detail in Chapter 5, Discovering Requirements. These techniques help us produce a Requirements Model (RM). An RM is a well-defined, contextualized model of our system's requirements. It will be the bridge that unites our requirements with our specifications.

A common question people pose when confronted with requirements and specification analysis techniques is: why can't I just write user stories? Let's answer this question…

The user story chaos

As mentioned in the preface, user stories tend to be an overloaded term in the Agile and BDD worlds. Asking the question what's a user story? will give you a dozen different answers. A user story can be a requirement, a feature, a description, an end goal, a high-level abstraction, a small piece of business value, and many other things, depending on who you ask. This can be a source of great confusion among stakeholders as well as developers. In order to be of use to the system builders, a user story must be scoped and contextualized. However, this is rarely the case. Some people think that anything they can fit into a As a <User>, I want to <do something> so that <I accomplish goal> template is something that developers and analysts can take away and work with. The result is what I call user story hell, where our product backlog is filled with hundreds of stories, ranging in their scope from vague and abstract business needs to implementation details to bug descriptions, and many more.

User stories were always meant to be the start of a conversation about the requirements. Unfortunately, they are often used as a catch-all device for any and all ideas and desires, relevant or not. My standard response when someone asks me to create, review, or manage user stories is: User stories for what exactly?

More often than not, what they mean by user story is what in this book we refer to as a feature, that is, a specific entity perfectly scoped and contextualized. User stories, on the other hand, may refer to a business goal, a high-level functionality, a low-level functionality, and anything in between. Therefore, the request to create a user story is meaningless and moot. I find user stories to be a great way of summarizing or describing some requirements domains – particularly capabilities – (more on these in Chapter 2, Impact Mapping and Behavior-Driven Development) but they are not domain entities themselves. They are just structured, summary descriptions of some domain entity such as a capability or feature.

User stories are merely attributes, short descriptions of our features or other requirement domain entities, so let's not get distracted by the trees and lose sight of the forest.


Don't get hung up on user stories. They are just descriptive devices for requirements domain entities. Nothing more, nothing less. We can create perfectly solid and usable specifications without using a single user story.

As system builders, one of our responsibilities is to identify business goals and provide system capabilities that help the stakeholders accomplish their goals. We achieve this by defining and implementing features, that is, system functionality. In the next few chapters, we will learn exactly how to go about doing just that.



In this chapter, we introduced the requirements domain, explored requirements and specifications, and defined some of the main entities in the requirements domain, namely stakeholders and goals. We discussed the relationship between these entities and outlined this book's approach for bridging the gap between requirements and specifications. Being able to create valid and verifiable specifications that accurately reflect the requirements is crucial to our system's success. Understanding the requirements domain allows us to analyze and model our requirements, which is the first step towards creating a specification.

In the next chapter, we will finish our exploration of the requirements domain by talking about two more domain entities, capabilities, and features.


Further reading

About the Author
  • Fred Heath

    Fred Heath is a freelance developer and consultant based in Wales, UK. Over the last 20 years, he's worked at every stage of the software development life cycle using a variety of languages and platforms and ended up falling in love with Ruby and its ecosystem. Fred enjoys solving tricky problems, FOSS, meta programming, Behavior-Driven Development, and Agile processes. He also frequently writes online and speaks at conferences about Ruby, software development, and best practices. Fred is always happy to hear from you and chat about Ruby and Rails on Twitter.

    Browse publications by this author
Latest Reviews (1 reviews total)
Contenido valioso no hallado en otros textos.
Managing Software Requirements the Agile Way
Unlock this book and the full library FREE for 7 days
Start now