concept requirement in category software development

1.5.2. Illustrating requirements with examples

SBE and Gherkin require delivery teams to support their conversations with practical examples. Illustrating requirements with examples helps reduce the level of abstraction and leads to clearer acceptance criteria—especially if the examples are concrete instead of vague.

SBE is different because it doesn’t see specification as a singular phase but rather as a process that spreads across multiple phases as requirements evolve and change (see figure 6.3). Specifications become tests; and tests, as you’ll see in chapter 7, become documentation.

Figure 6.3. SBE in the software development process. Specification spreads throughout multiple phases.

By evolving requirements, I mean that the precision level of your requirements changes throughout the life cycle of an executable specification. Every requirement starts as a vague goal with a high level of uncertainty. As you implement it, uncertainty decreases, because the requirement gradually becomes working code. As you’ll see, SBE and Gherkin have a different feedback loop at each stage of the life cycle, which helps decrease uncertainty even further than in other software development processes.

As you cross each threshold, the precision level of your analysis increases (see figure 6.5). The more precise you are, the better you understand the implications of implementing a requirement.

Figure 6.5. As the need for detail increases, so does the precision of artifacts that appear during development.

Business goals are broad directives that sometimes don’t provide a specific solution. Requirements are less abstract; they define what needs to be built for whom in order to achieve the high-level goal. Solutions are precise plans for features, interaction flows, and user interfaces. Because software is comprised of thousands of moving parts, no solution is fully precise until it’s implemented as working code. And only after the code is released to production do you get the feedback needed to asses whether a business goal has been met, which removes any remaining ambiguity.

6.3.1. Conveying requirements as user stories

A user story lets you convey a glimpse of a requirement as a product backlog item. The item becomes a ticket for a future conversation. Through user stories, you can negotiate the priority of any given requirement, discuss possible solutions and scope, and make some estimates. They’re used for planning.

In this chapter and throughout this book you’ll notice that I talk a lot about estimating work. For the agile team, estimating work goes beyond trying to nail down better predictability; it also encourages the team to understand the requirements in greater depth, think harder about what they’re building before they start, and have a greater investment in what they’re building by committing to a timeframe with their peers. You’ll notice that estimations are a part of the case studies at the end of several chapters and are used in combination with other data to see a broader picture of your team’s operation. I encourage all of my development teams to estimate their work for all of these reasons, and I encourage you to consider estimating work if you’re not doing it already.

Requirements, developers, work, team, and process are all focal points.

The interesting thing here is that you need to compare your consistency when requirements are static against when they change. To do that you need to measure your team’s consistency and you need to track when requirements are in flux.

Velocity alone is a terrible metric to measure how well a team can handle change and as a result is often a bone of contention when requirements are changing. If a team makes a commitment and starts a sprint, and then midway through the process the end goal moves, the team is set up to miss their commitment. You can reestimate or refactor your sprint goal, but in the grand scheme of things it will look like your team went through a patch of low productivity when perhaps they were more productive than ever.

Figure 10.12. Velocity for this team is inconsistent, but total completed tasks are actually increasing. This is a typical indicator that the team completes tasks consistently despite changing commitments and/or requirements.

Defines task-based activities that are aligned with requirements. This means that the activities are linked to requirements and that all changes are traceable to their requirements.

You can link requirements and defects to coding items, and vice versa. This referencing makes it much easier to validate that the work is done to plan and that the plan is getting done. This end-to-end referencing provides much more scale than using the plain story cards that are used by some Agile approaches, although this may be sufficient in many circumstances too. A common method is to add a ticket number to the check-in command so tools can cross-reference requirements with coding artifacts. An essential method is using change-sets. A change-set is a group of changes made to the system but processed as an atomic unit. Consider the different changes a developer must make to implement a new feature. Instead of checking in each change separately, they can be checked in as a single atomic transaction. This way, the system can verify that all changes are traced to their respective requirements and can update the status of the baseline.

A basic premise of Agile ALM is that work should be aligned to the customer’s requirements. One approach to doing this is called outside-in. Too often, work isn’t based on specific customer requirements, and sometimes requirements aren’t defined at all or aren’t tracked through the process. Other times, the technical staff and the customer, may be speaking different languages in defining the requirements of the software. The outside-in approach takes the right focus and it leads to a different approach in measuring success; it values customer satisfaction and other soft attributes. Its main drivers are as follows:^[9]

Figure 3.1. Software engineering goes through a workflow cycle: requirements management kicks off the development process. Requirements belong to releases. Release management triggers the design/development of software, which in turn creates the artifacts implementing the requirements. Those implementations are then put into version and build management and are provided in releases.

Several other teams noticed a significant reduction of rework, including LeanDog, a group developing an aggregation application for a large insurance provider in the United States. Their application presents a unified user interface on top of a host of mainframe and web-based services and is further complicated by a large number of stakeholders from across the country. Initially, the project suffered from many functional gaps in requirements, according to Rob Park, an agile coach at LeanDog who helped the team with the transition. He said,

Build a reference example:
When: Requirements are impossible to quantify

For teams who worked on projects where the requirements were vague and required a lot of upfront analysis, the preparation phase started two weeks before the collaborative workshop. This allowed analysts to talk to business users, collect examples from them, and start refining the examples. Teams that had more stable requirements started working on examples a few days before, collecting the obvious open questions and addressing them. All these approaches help to run a bigger workshop more efficiently.

Traditionally, once a project starts, a requirements package is created and then is “signed off.” The project manager assumes that this sign-off results in a fixed set of requirements and that now planning can begin. The project manager estimates how long it will take to complete the requirements and creates the project plan. The plan predicts that the project will be finished by a certain date, and that date is communicated back to the customer.

The fundamental flaw in this approach is that the plan, which drives everything, is based on an assumption that the requirements are fixed and won’t change. Experience has shown us that this is never the case; requirements are never fixed—they always change. When the requirements change, the plan is affected; and as a result, the completion date needs to change too. Unfortunately, in many cases, that is impossible, and the team has to deliver by the date they committed to. This is when a major crisis occurs and the project starts to go out of control.

The value-driven agile approach switches the whole mindset. It assumes from the start that whatever requirements exist up front are not fixed and that they will change. The agile mindset also assumes that you have to deliver by a certain date. This approach fixes the time and resources and leaves the requirements undetermined. To us, this approach more closely resembles the reality of creating software. Now the whole notion of value-driven makes perfect sense. When you have a fixed amount of time in which you aren’t sure whether you can deliver all the requirements (because they will change and hence the time needed to finish them will change), the natural reaction is to prioritize the requirements and finish first those that add the most value to the customer.

You may be thinking, “What about the requirements that aren’t finished by the delivery date?” That is the reason you use the value-driven approach. You acknowledge the fact that not all of the requirements will be completed by the delivery date. The important question to ask is whether you have delivered enough features to support a system that provides value to the customer.

Figure 2.4. As a team addresses its issues, a process becomes more agile with early customer demonstrations and dedicated time to adapt, re-plan, and adjust. True iterative development takes place, and requirements, design, and coding frequently happen concurrently.

Managing changes and decisions during development is still a difficult feat. You’re trying to stay on schedule, meet the customer’s needs, and support nonfunctional requirements such as performance needs. Discoveries require diligent, collaborative decision making. You’ll refine requirements, reprioritize the work, and re-plan based on what you encounter.

When you kicked off your project, the customer provided their priorities in the tradeoff matrix (schedule versus resources versus costs, and so on). You can use this matrix to help the customer decide how to react to the change in requirements and how to best triage the discovery.

Figure 1.2. Acceptance test-driven development drives implementation of a requirement through a set of automated, executable acceptance tests.

Furthermore, one of the most striking benefits of using tests as the specification driving development is that tests typically employ specification by example instead of abstraction or prose (although there should almost invariably be some amount of prose involved—things are not black and white in this respect either). In other words, instead of the traditional “the system shall calculate tax” pattern familiar in requirements documents, specification by example promotes expressing the requirement through examples such as “for a $20 subscription with a tax rate of 10%, the system charges a total of $22 from the user’s account.”

For this simple requirement, the difference between the traditional “system shall” and an example-based version might not be that significant—after all, we all know how to calculate tax in such a trivial case. However, the requirements we meet at work are typically not as trivial, and the risk of misunderstanding is much higher. For instance, applying multiple taxes for a given transaction might need to employ different calculation rules in different locales, which can be clarified enormously through concrete examples.

Specification by example is a natural fit for our intuition and makes it easier to relate the requirements to the concrete world and our software. Specification by example can also be seen in TDD. Whereas acceptance tests specify by example the desired behavior of the system, the examples and the desired behavior specified with unit tests are specifications about the desired implementation rather than about the functionality delivered.

2.1. From requirements to tests

Imagine you are implementing a subsystem for the corporate collaboration software suite^[1] that’s responsible for providing mail-template functionality so that the CEO’s assistant can send all sorts of important, personalized emails to all personnel with a couple of mouse-clicks. How would tests drive the development of the said subsystem? You’re going to know the answer to that question by the time you’ve finished reading this chapter; but, as with any system, it starts with decomposing the requirements into something smaller and more concrete.