Introduction

In Chapters 3 and 4, we discussed multiple techniques and frameworks of customer research. Using validated knowledge about the customers and their problem to solve, or Job-to-Be-Done, product features are sequenced and prioritized based on user needs. This information can be captured and documented in multiple ways.

Chapter 5 covers different frameworks and techniques for creating and maintaining requirements in IT – whether it is software or hardware development. It covers traditional requirements documents – how those are created, what information they cover, and how those are approved, updated, and maintained. As part of the requirements document, we categorize requirements into functional and nonfunctional and discuss software models as they apply to requirements definition. We will review use cases and user scenarios and cover UML (Unified Modeling Language) methodology and formal techniques for process modeling. In contrast to monolithic well-defined traditional requirements, we will review the details of the Agile approach to requirements gathering via collaboration, the role of IT professionals in the process, as well as continuous validation and adaptation that are happening in Agile delivery. We will review the concept of a product backlog, the taxonomy of its elements, and different techniques for creating backlogs, such as story mapping, as well as prioritization mechanisms that are used in product backlog management. We will talk about risk and dependency management as it applies to the requirements definition.

Requirements in Software Development

Software requirements based on customer research and product definition are the basis of all software development work. Poorly defined or inadequate (inaccurate, incomplete, ambiguous) requirements are the major cause of poor-quality software. The goal of software requirements is to describe the capabilities, features, and constraints of the software products. Requirements contain information on how this product works, how users interact with the product, and, most importantly, what customer problem it solves.

The requirements are usually written in a language that everyone can understand. For many globally distributed teams, requirements are written in a natural language, frequently in English. However, some organizations use requirements templates and specialized techniques, such as UML (Unified Modeling Language) and RUP (Rational Unified Process), which will be discussed later in this chapter.

The goal of software requirements is to define what the system needs to do. It can be viewed as a checklist that designers, developers, and testers use to produce software products. Requirements are based on the vision, mission, organizational OKRs, market research, user research, and the validated problem that the product is solving for the customer.

and many other aspects of the system to be built.

Requirements’ format, elicitation techniques, documentation, and approval (sign-off) processes differ drastically among the organizations. In this chapter, we will review different methods in a historical sequence, starting with a traditional software requirements specification (SRS) document.

Requirements in Traditional Project Management

Requirements traceability matrix is a list of requirements, their attributes (e.g., priority), references to test cases and validation mechanisms, status, and other relevant information. A sample traceability matrix template is provided in Figure 5-1.

 Topic for a Group Discussion

Review each field on the requirements traceability matrix format provided in the sample. Which data is informative and which can be replaced by other, more meaningful, data points? What information is missing? How would you optimize the template provided in this sample?

Software Requirements Specification (SRS)

In traditional project management (Waterfall), software requirements specification is a document that describes features and capabilities provided by the software along with its performance requirements. It also describes the functionality the product needs to fill  the stakeholders' (business customers, end users, clients) need.

A software requirements specification (SRS) usually contains functional (customer-directed capabilities) and nonfunctional requirements (system-based features, such as availability, reliability, and security). Software requirements specification serves as a foundation for a handshake between the customers and the software provider on how the software product should function. The goal is to provide the relevant level of detail upfront to limit any redesign or changes to the list of required features. Usually, it is a comprehensive, well-defined document, which provides a clear and thorough understanding of the product to the development team.

In traditional project delivery, the communication between the development team and customer is limited throughout the development process, so SRS serves as an internal contract for the work that is being performed. Any changes to SRS are considered scope changes to the product and have to be reviewed and approved through the change management process based on the impact on product delivery that is estimated by the delivery team or the development lead.

Typically, SRS contains hundreds of pages of documentation, accompanied by appendices containing data models, descriptions of business logic, a set of assumptions, wireframes, and other relevant information. SRS is usually written and maintained by a product manager, business analyst, technical writer, or (in smaller companies) a systems architect or a software developer. SRS users include managers, software engineers, test engineers, maintenance engineers, customers, and managers.

Frequently, business analysts start their work on software requirements from the Business Requirements Document (BRD), which describes the high-level business needs. This document is extended by the Functional Requirements Document (FRD), which outlines the functionality required to fulfill the business need. Based on this information, they proceed to create SRS, which contains technical implementation details and serves as a primary input into the development. This nomenclature may differ depending on each company's internal processes and practices.

There is an SRS standard developed by the Institute of Electrical and Electronic Engineers (IEEE), the world’s largest technical professional organization dedicated to advancing technology for the benefit of humanity. The IEEE Recommended Practice for Software Requirements Specifications (IEEE Standard 29148-2018) [1] discusses a number of topics that should be considered during the creation of an SRS. The SRS is defined by IEEE as a specification for a particular software product, program, or set of programs that perform certain functions in a specific environment. IEEE advises that SRS writer(s) shall address the following:

IEEE provided the following samples of requirements:

Example 1. When signal x is received [Condition], the system [Subject] shall set [Action] the signal x received by [Object] within 2 second [Constraint].

Example 2. At sea state 1 [Condition], the Radar System shall detect targets at ranges out to [Action or Constraint] 100 nautical miles [Value].

Example 3. The Invoice System shall display pending customer invoices [Action] in ascending order [Value] in which invoices are to be paid.

Software Design Specifications

Software requirements document usually does not provide details of software design, that is, description of specific subcomponents of a system and their interfaces with other subcomponents. This includes descriptions of software architecture, its structural modules, data models, the flow of information or control between modules, and data structures.

Design constraints may be reflected in SRS as nonfunctional requirements.

 Five key questions to review:

1. 1.

   What is a software requirement?

    
2. 2.

   What is included in a software requirements specification document?

    
3. 3.

   What is the difference between functional and nonfunctional requirements?

    
4. 4.

   What is the relationship between a software requirements specification document and a software design specification document?

    
5. 5.

   What are the topics that IEEE advises to cover in the software requirements specification based on Systems and Software Engineering – Requirements Engineering standard?

    

Use Cases

Requirements can be expressed in a natural language or in any agreed-upon format. Use case methodology is an effective approach for documenting requirements that originated in object-oriented programming. A use case is defined as a list of actions or steps defining the interactions between a role and a system to achieve a predefined objective. This could be a human or other external system.

The concept of use cases was introduced in 1987 by Ivar Jacobson, who described how this methodology was used at Ericsson to capture and specify requirements of a system using textual, structure, and visual modeling techniques to drive object-oriented analysis and design. In a nutshell, use cases are a methodology that allows for capturing, modeling, and specifying the requirements of a system. It is a combination of a software requirements specification and an implementation-based system requirements specification. According to the Software Engineering Body of Knowledge (SWEBOK) [3], these use cases belong to scenario-based requirements elicitation techniques, as well as model-based analysis techniques. In addition to that, use cases support narrative-based requirements gathering, incremental requirements definition, and modern testing techniques, such as acceptance-driven delivery.

 Tip

Use cases are written in such a way that they are free of implementation details. The concept is to represent functionality rather than describing implementation. For example, the best practice is to specify that a user selects a specific option rather than stating that the user clicks a button.

In the following, we provide a sample use case for an online bookstore:

Title: UC-1 Select a book to buy

Description: While browsing books in a bookstore, a user is able to select a book for purchase.

Actors: Customer, System

Trigger(s): A website provides a set of recommended books based on customer’s preferences.

Pre-condition: A user has a profile set up with preferred book type and prior purchase history.

Postcondition: A user selects a book and places it in a shopping cart.

Normal flow:

1.  The user views the proposed books.

2.  The user chooses the book to view details.

3.  The system presents book details and updates the set of recommended books based on the selection.

4.  The user chooses to purchase the book reviewed.

5.  The system presents a list of books that the users who purchased the originally selected book also have bought.

6.  The user reviews the list and chooses a book to purchase without reviewing details.

7.  The system allows for one-step addition of recommended items to the shopping cart.

8.  The user selects an option to view the shopping cart.

9.  Shopping cart content is presented to the user.

Alternative flow:

2A.

1.  The user chooses to buy the book without viewing the details.

2.  Proceed to step 7.

4A.

1.  The user chooses not to purchase the book.

2.  The user exits the system.

4B.

The user chooses not to purchase the book.

The user is presented with a set of recommended books.

Proceed to step 1.

A set of use cases representing the complete functionality of a system is described in a use case diagram, as shown in Figure 5-2.

 Topic for a Group Discussion

Review the use case diagram in Figure 5-2 and discuss who are the actors, how authentication is set up, and how payment is performed in this specific system. Review additional use case diagrams in the following UML tutorial and explain the functionality described there. Source: www.uml-diagrams.org/examples/online-shopping-use-case-diagram-example.html?context=uc-examples

User Stories

User stories are short, simple descriptions of a feature told from the perspective of the actor who desires the new capability, usually a user or customer of the system. Each user story expresses one very specific need that a user has. It can be viewed as a minimum requirement focused on user needs.

User stories are used in the Agile development process to describe product features. They allow developers to focus on what the user need is. The best user stories are based on user research and market analysis, as described in Chapter 4 – they aren’t “made up” and actually reflect user needs.

The difference between use cases and user stories is that user stories are written from the user perspective (hence the term “user stories”) rather than that of a business analyst describing the system’s functionality.

They are focused on outcomes rather than scenarios. And most importantly, they do not describe “how” to achieve the desired functionality; they focus on “what” this functionality should be. User story allows developers to design a functional solution to the user problem it presents.

User stories follow the standard format based on role–action-benefit (or “who–what–why”).

Some user story examples include the following:

As an online book shopper, I want to view the details of the book in an online store so that I can make an informed decision.

As a mortgage provider, I want to view the requestor’s credit score so that I can approve or decline their mortgage based on the risk associated with it.

As a service provider, I want to authenticate my customers so that I can provide personalized service based on their subscription type.

There are several rules for a user story.

“3 C’s” are an important characteristic of a user story that allows for keeping the purpose of the user story in perspective. This model was proposed by Ron Jeffries in 2001 [4]. These 3 C’s include the following:

1. 1.

   The first “C” is the user story in its raw form, the Card (i.e., index card). The concept is that the whole story has to be concise, that is, fit into a single index card. It also has to do with the way user stories are grouped together on a Kanban board (Kanban board is a way of visualizing work in progress based on user stories that are being delivered. The concept comes from Lean. In Japanese, “Kanban” literally means “visual card”). See an example in Figure 5-3.

    

There is an opinion that for ATDD, tests always have to be automated. This is not accurate. Despite us advocating for test automation and despite the tools, such as Fit/FitNess or Cucumber, ATDD is highly beneficial even if it is not automated (2).

ATDD is built on the concept of Test-Driven Development (TDD). ATDD process is built “backward.” First, a developer writes a failing unit test that demonstrates that the existing code base does not fulfill the requirement. Once the unit test fails, they write the production code until the test passes the requirement. When the test is passing, they clean up the code and improve the design. Similarly, in ATDD, the team creates one or more acceptance-level tests for a feature before beginning work on it.

and many other relevant data points.

Other ways to decompose user stories are by user type (new vs. repeating user), by book type (paper vs. digital), by price, by geography, by language, and so forth.

 Topic for a Group Discussion

Decompose the following user story and rewrite it as needed:

As a user, I want to log on to the online bookstore to check my order status.

The benefits of user stories include the following:

 Five key questions to review:

1. 1.

   What are user stories?

    
2. 2.

   What is the difference between user stories and use cases?

    
3. 3.

   What does the acronym INVEST stand for?

    
4. 4.

   Why ATDD practice is driving quality improvement?

    
5. 5.

   What are the benefits of using user stories vs. software requirements specifications? What are the drawbacks?

    

However, Agile requirements are not a collection of individual user stories. Given that for larger systems, there are usually hundreds of user stories developed, they need to be prioritized, sequenced, and organized in a meaningful way. This way of organizing, prioritizing, and maintaining user stories is called a product backlog.

Product Backlog

The product backlog is a collection of prioritized discrete items of different types connected by parent-child relationships. Relationships between product backlog items are referred to as “product backlog taxonomy” shown in Figure 5-4.

Agile does not prescribe the types of elements in the product backlog; however, traditionally, functional requirements are represented in user story format. The team using the product backlog determines the format they choose to use and looks at the backlog items as reminders of the aspects of a solution the team may work on.

Besides user stories, other product backlog elements may include the following:

Epics. Epic captures a large body of work. It represents a feature that may be independently released to end users. It is usually written in the same format as a user story; however, this is not necessary. For example, “As a customer, I want to pick a flight ticket so that I can travel to a conference.” This epic includes “selection” criteria, “view details” functionality, and “select functionality.”

Technical Tasks. Tasks do not provide user functionality; however, they are necessary for software development. For example, deploying applications on the cloud, building test environments, implementing security features, upgrading software tools, and so forth.

Spikes. Spikes are research items. They are created to research the tool, define strategy, test performance, compare implementation methods, and so forth. They have an outcome, which is learning and potentially implementation or tooling decision, but they do not produce shippable products. If there are prerequisites to user stories, spikes usually address those prerequisites and precede user stories they are supporting.

Subtasks. User stories, epics, technical tasks, and sometimes even spikes may be broken down into subtasks (sometimes referred to as “tasks”). While each of these backlog item types either provides end-to-end functionality or provides an answer to a specific question, subtasks are used to divide responsibilities between team members in implementing any of these items, for example, coding, testing, designing, etc. Subtasks are helpful in planning and aligning as a team during execution.

Agile is a framework, not a methodology, so it does not prescribe specific taxonomies or formats for product backlogs. Each organization optimizes against its needs and processes. For example, there may be other item types in Agile organizations, such as bugs, risks, and so forth. It depends on organizational size, structure, reporting, and tracking. Since Agile assumes continuous improvement, many organizations experiment with the most efficient structure of the product backlog.

 Tip

Frequently, product backlog taxonomy is prescribed or configured within an organization by the software delivery life cycle tool that this organization is doing. To enable organizational-level transparency and reporting, it is important to standardize product backlog taxonomy across the organization. For example, if an organization is heavily regulated, it may implement Risk issue type or create a new one, for example, Compliance Approval. As long as there is consistency, training, and a glossary of product backlog elements, customization is encouraged. However, having more than five to seven item types is usually confusing and creates an unnecessary overhead.

However, this logic is impacted if there are constraints. For example, user story 1.2 describes a regulatory requirement that has to be implemented by a specific date. In this case, it does not matter that there is a significant effort to have it implemented, and this user story gets prioritized “just in time” based on the date when the regulation goes into effect and the estimation of the time that will require to deliver, test, and debug this user story.

While product backlogs represent a hierarchical structure with parent-child relationships, they are not usually created as such. An effective technique of creating a balanced, well-thought-through product backlog is referred to as “story mapping.”

Story Mapping

Story mapping (a.k.a. user story mapping) is a valuable tool for software development. The concept of story mapping was introduced by Jeff Patton (3). In this process, the team explores the user story’s life cycle, starting with opportunities and moving deeper into discovery and then sequencing these user stories into MVP and subsequent releases.

 Tip

Jeff Patton provides a quick reference to story mapping – a highly informative document, which serves as a foundation and a guide for the story map workshops. This reference can be downloaded from his website: www.jpattonassociates.com/wp-content/uploads/2015/03/story_mapping.pdf. Review the document and discuss practical takeaways from this approach.

In a nutshell, a story map tells a story about a type of person doing something to reach a goal. Story map represents features that comprise the major product features, which are later organized into subsequent product releases. A sample story map is provided in Figure 5-5.

It is a prerequisite to have a general understanding of the “big picture” in order to create an informed story map. The story mapping session usually starts with reviewing OKRs for the product, major functionality, persona types, and their needs and then moves top to bottom from requirements elaboration perspective: from “themes” (or functional categories) to product features, and sometimes even to user story level, so that the finished product may be used as a skeleton for creating a product backlog.

As it is shown in the preceding example, the user story map starts with the personas, defines epics (or sometimes collections of epics), and then decomposes those into features and user stories. Many story maps represent the product at the epic level and above, hence the term “story map” rather than “user story map.”

 Five key questions to review:

1. 1.

   What is a product backlog?

    
2. 2.

   What is the structure of a product backlog?

    
3. 3.

   Which elements are mandatory and which are recommended?

    
4. 4.

   What is a story map? What are its elements?

    
5. 5.

   Why is story map a more accurate term than “user story map”?

    

Based on alignment and prioritization achieved with story mapping, the structure of the product backlog is shared between all stakeholders and can be used as a more flexible analog of a software requirements document.

Key Points