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
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
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.
Tip
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.