Chapter 3
Requirements

A software requirement is a rule the software must conform to: what it must do, how well, and within what constraints or limits.

3.1 Types of Requirements

There are two main types of requirements:

1. Functional requirements are “A description of a behavior that a system will exhibit under specific conditions” (Wiegers & Beatty, 2013, p. 599). For example, “If the user activates the ‘log in’ button, the login page will appear.” Functional requirements answer the question, “What must the software do?”
2. Nonfunctional requirements are “A description of a property or characteristic that a system must exhibit or a constraint that it must respect” (Wiegers & Beatty, 2013, p. 600). For example, “If the user activates the ‘log in’ button, the login page will appear within 500 milliseconds.” This nonfunctional requirement has a characteristic that the system must exhibit: responsiveness. Responsiveness is also called a quality attribute. An example of a nonfunctional requirement about respecting a constraint is, “The GUI toolkit must be able to display non-rectangular windows.”

Figure 3.1 shows a simple example of a design failing to reflect a nonfunctional requirement and a functional requirement.

Note. This rolling table fails the nonfunctional requirement of fitting through an average door and the functional requirement of having four legs.

3.2 Why Requirements Matter

The design and implementation of software should, ideally, follow from the requirements. Here are some ways requirements are helpful and reasons they are important:

• When developers aren’t given requirements, they might prioritize functionality they personally think is important or fun to implement, but what developers want to implement might not make the project successful.
• When multiple developers are working on the same code, requirements can help them stay in sync and pursue the same goal. Without requirements, time, effort, and money can be wasted implementing conflicting code.
• When requirements aren’t specified, it’s easier for project stakeholders (e.g., clients, partners, investors, consultants, management) to influence the project toward satisfying their own (possibly fleeting) wants or needs. This can result in the project drifting away from what it was originally intended to do—and can lead to project failure.
• Requirements are helpful for communicating about software with stakeholders, keeping track of everything that needs to get done, and helping you and the client decide what really needs to get done (clients sometimes don’t know what they really need).

3.3 What Makes a Good Requirement

Teams or organizations can choose their own standards for what makes a good requirement. Here is one set of standards (Texas Department of Information Resources, 2008):

Requirements should be . . .

• Correct: What they say is right.
• Unambiguous: There is only one way to interpret them.
• Complete: They cover all that’s important.
• Consistent: They aren’t contradictory.
• Ranked for importance and/or stability.
• Verifiable or testable: There’s a way to figure out if they’re satisfied.
• Modifiable: They can be changed.
• Traceable: It’s possible to figure out where they came from.

Requirements should also be . . .

• Cross-referenced to earlier documents that relate.
• Uniquely identifiable.
• Organized for maximum readability.

3.4 Requirements Elicitation

The process of gathering requirements is called requirements elicitation. Requirements can come from any stakeholder, including clients, managers, users, governments, developers of software to be integrated with yours, the development team, and yourself. Requirements elicitation involves both detecting stakeholders’ wants and needs and using your professional judgment to decide which requirements to focus on.

To detect stakeholders’ wants and needs, communicate and observe. Some methods:

• Interviews: Structured (questions defined ahead of time), semi-structured (some questions predefined, some generated during interview), or unstructured conversations.
• Focus groups: Small, group conversations in which the participants discuss topics among themselves, with moderator guidance.
• Lab studies: Participants perform tasks in a controlled setting (e.g., try to use an early prototype, then give feedback).
• Exploratory research: Multiple methods of immersing oneself within the world of relevant people and products, with the purpose of gaining knowledge and developing empathy for stakeholders. For example, after doing a fly-on-the-wall observation, you realize that people can’t find Aisle 25 because it’s in an unexpected place. You decide to prioritize the Aisle Map feature in the store’s app.

Depending on the software development environment, these methods might be the jurisdiction of specialist researchers in marketing or interaction design. Hanington and Martin (2019) describe these specialist methods (and many other relevant methods) in more detail.

Developers can elicit requirements, too, by having conversations with stakeholders. There are factors that can affect the success of that approach, however.

• Stakeholders might not have experience or expertise. Developers can help bridge the gap between what the stakeholder wants and what is technically feasible and reasonable (e.g., given time, cost, and scope, what is also known as the triple constraint).
• Stakeholders might not have good ideas. They might be incorrect about what they or other people want or will use. Developers can sometimes provide guidance toward better ideas, but developers can also have bad ideas. Methods such as focus groups, usability testing, and releasing a minimum viable product (MVP) can help with figuring out whether users will use (and pay for) the software.
• Stakeholders might not know what they want. They may have a rough idea, or an idea that’s at odds with their wants or needs.
• Stakeholders might want what’s bad for them or others. For example, users want apps that make their face beautiful in photos, such features may promote unrealistic beauty standards.
• Stakeholders are humans. They communicate imperfectly.

With experience, you can learn how to effectively gather relevant information from stakeholders and make your own judgments about how that information translates into requirements.

3.5 Nonfunctional Requirements

Nonfunctional requirements describe how well the software needs to perform or what constraints it must respect.

Examples of nonfunctional requirements:

• Response time should be a few seconds or less in all operating environments.
• The front-end design must be evaluated using the Inclusivity Heuristics by at least two people each Sprint.
• The software must be available 24 hours a day, seven days a week, and must have an uptime of 99.99%.

Notice that each nonfunctional requirement has a quantity. That helps make it testable (a criterion for a good requirement).

3.5.1 Quality Attributes

Quality attributes are words for describing “a service or performance characteristic of software” (Wiegers & Beatty, 2013, p. 601). Some common quality attributes are as follows.

• Maintainability: Amount of effort needed for developers to update, refactor, or otherwise modify the software’s code.
• Portability: Amount of effort needed to run the software on different platforms.
• Reliability: How often the software’s functions succeed or fail.
• Efficiency: Number of resources the software requires.
• Integrity: How frequently the software loses data.
• Memorability: Amount of time users must spend relearning functionality.
• Flexibility: Number of different ways the software can be used.
• Interoperability: Ease with which the software can integrate with other software.
• Reusability: Extent to which the code can easily be used to solve other problems.

Each quality attribute can be converted to a scale. For example, the lowest value on a reliability scale for a single could be “the function succeeds 0% of the time,” and 100% would of course be the opposite pole. Given this scale, we can specify a nonfunctional requirement by defining a performance threshold:

• The function must have high reliability (succeeds >99% of the time).

When you select quality attributes for your software, you are prioritizing what qualities matter most to you/your team/the project. Ideally, your team would keep these quality attributes (and the corresponding nonfunctional requirements) in mind for the duration of the project. If the software is not meeting the nonfunctional requirements, either the software or the threshold of acceptability needs to change.

3.5.2 Constraints

Some nonfunctional requirements are not about quality attributes and are instead about staying within constraints. The following are example types of constraints (Wiegers & Beatty, 2013):

• Those limiting technology choices (programming languages, frameworks, databases, application programming interface (API) types, etc.).
• Those limiting what platforms are targeted (e.g., mobile versus desktop, iOS versus Android).
• Those limiting what about the software can change (e.g., for backward compatibility).
• Those limiting how code can be written (e.g., following particular coding and documentation standards).
• Those limiting how data can be handled (e.g., must only be stored on US servers).

A conceptual difference between constraints and quality attributes is that constraints are often externally mandated, while quality attributes can be chosen internally by the team.

3.6 Functional Requirements

Functional requirements described what the software must do.

Example functional requirements:

• When the “register” button is activated, the user’s information is added to the database and a “thank you for registering” screen displays.
• As a wholesaler, I want to see the wholesale and retail prices when I go to “product view” so that I know how much money I’m going to make.
• Given a user has performed at least one editing action, when they activate the “action history” window, they see a list of editing actions they have taken.

Each of these functional requirements is formatted differently. There isn’t a name for the first format; it simply states what should happen when a particular action is taken in the software. The second uses user story format, which is common in Agile software development. This format emphasizes the user, what the user is trying to do, and their motivations. The third requirement uses the given-when-then format (see Agile Alliance for more information), which incorporates context. This format is commonly used to write user story acceptance criteria: a set of statements that, when true, indicate that the user story has been completed.

A more formal way to write functional requirements is the use case format, which follows a template. Figure 3.2 contains an example use case using a simple template.

Figure 3.2 Simple Use Case

3.6.1 User Stories

User stories are a method for specifying functional requirements. They describe a small piece of the software’s functionality in a simple and easy-to-read sentence. They are written in plain English so that nontechnical people (e.g., users, clients, other stakeholders) can understand them.

User stories can be written on 3 × 5 index cards and then stuck on a wall or whiteboard. They can also be typed into task and project management systems (e.g., Jira, Asana, and the like). Figure 3.3 provides a few examples of user stories within the context of a project (they have priorities and other project-related information attached to them).

Figure 3.3 User Story Functional Requirement Examples

Want more examples of user stories? Mountain Goat Software provides 200 example user stories [PDF] (Cohn, 2004). They list only the “As a . . .” part of the user story requirement.

Anyone on the team—or any project stakeholder—might come up with user stories. Once the user stories are initially defined, they can be used to start a conversation with the client and others on the team. Clients can guide you on setting priorities for user stories. This conversation is also a good time to get more details about the user stories, which should be added to the card.

What makes a good user story? Besides the characteristics of good requirements listed earlier in this chapter, the INVEST acronym (Wake, 2003) can help you remember characteristics of good user stories:

• (I) Independent: Does not have unnecessary dependencies or overlap with other user stories.
  • Two user stories that overlap:
    • “As a new user, I want to register so that . . .”
    • “As a new user, I want to register using my Google account so that . . .”
  • Set of user stories that don’t overlap (but some user stories need to be completed before others—that’s ok):
    • “As a new user, I want to view the registration page so that . . .”
    • “As a new user, I want to register using Facebook so that . . .”
    • “As a new user, I want to register using Google so that . . .”
    • “As a new user, I want my registration details to be stored so that . . .”

• (N) Negotiable: Encourages instead of discourages discussion and gives developers flexibility.
  • Does not encourage discussion: “As a logged in user, I want to choose either black or white so that . . .”
  • Encourages discussion: “As a logged in user, I want to choose from multiple colors so that . . .”
• (V) Valuable: Fulfills a user need.
  • Does not fulfill a user need: “As an Enterprise user, I want to watch a little race car drive around the screen so that I can do something fun while requesting API end points.”
  • Fulfills a user need: “As an Enterprise user, I want to import my API end point requests so that my requests take less time and are less tedious.”
• (E) Estimable: Can be given a time estimate.
  • Difficult to give a time estimate: “As a new user, I want enough encouragement to register so that I’ll register.”
  • Easier to estimate: “As a new user, I want to compare plan pricing so that I can decide which plan to choose.”
• (S) Small: Can fit into a single development period (e.g., a two-week Sprint)
  • Probably too large for a Sprint: “As a user, I want to play chess on my phone so that I have something to do while waiting at the pharmacy.”
  • Smaller: “As a user, I want to move my pawn so that I can take my turn in chess.”
• (T) Testable: Possible to determine it’s done.
  • Difficult to determine whether it’s done: “As a guest user, I want to be satisfied with my experience so that I will want to sign up.”
  • Less difficult: “As a guest user, I want to try out the AI text generator without registering first so that I can decide whether to subscribe.”

There is some overlap between INVEST and the general characteristics of good requirements mentioned above (which is comforting), but you might find that INVEST is easier to remember.

How do you know when a user story is done? This is negotiated with the client and added to the user story as acceptance criteria. Acceptance criteria say what must be true about the functionality specified by the user story for the user story to be considered done (i.e., establishing the Definition of Done for the user story). Figure 3.4 adds a DoD to one of the user stories from Figure 3.3. The DoD is composed of acceptance criteria following the given-when-then format.

3.6.2 Use Cases

Use cases are a more formal method of specifying functional requirements. They are structured descriptions of what a system is required to do when a user interacts. Figure 3.2 showed a simple use case example, and additional examples can be found in the Digital.gov Usability Starter Kit PDF about use cases and personas (US General Services Administration, 2014).

As use cases are less common in Agile, the remainder of this section will provide only a summary of how use cases are structured.

Required Parts of a Use Case

Every use case has the following.

• Name: A short title for the use case that often starts with a verb (e.g., “Schedule weekly wellness check”). The name briefly states the user objective the use case will describe.
• Actor(s): The user or users (human/nonhuman/computer) that are interacting with the software (e.g., “Medical staff”).
• Flow of events: Sequence of actions describing the interaction between the actor and the software (a.k.a. “basic course of action” or “success scenario”).

Sometimes, the actor is implied through the flow of events (e.g., “Shopper selects the calendar icon”). Other times, the actor is stated separately from the flow of events (e.g., “Actor: Shopper”).

Additional Parts of a Use Case

The following are sometimes included in use cases.

• Identifier: A unique way of referring to the use case (e.g., UC-002).
• Preconditions: What must be true before the flow (e.g., “The shopper has added at least one product to their shopping cart”).
• Postconditions: What must be true after the flow (e.g., “The shopper received an order confirmation email”).
• Business relevance: Justification for why the use case exists.
• Dependencies: Other use cases the use case relies on. The unique identifier is handy for this part.
• Extensions: Contingencies, alternate routes, and branches to other use cases.
• Priorities: The importance of the use case.
• Nonfunctional requirements: How well the software must perform during the flow.

3.7 Requirements Specification

The process of writing down requirements is called requirements specification. Used as a noun, requirements specification refers to the document that contains the requirements. That document may also be a software requirements specification (SRS). The best way to learn about SRSs is to look at some.

Freely available SRS examples (including some for open source software):

• SRS for apps and a data repository for distributing manufacturing data [PDF] (Hedberg et al., 2017).
• SRS for data system that assesses conservation practices [PDF] (CEAP, 2006).
• SRS for an app that splits and merges PDFs [PDF] (Spyridonos, 2010).
• SRS for software that processes electroencephalography data [PDF] (OpenVIBE, 2018).
• SRS for library software [PDF] (Eaker, 2006).

If any links are broken, try the Wayback Machine.

3.8 Summary

There are two main types of software requirements: functional and nonfunctional.

A functional requirement is “a description of a behavior that a system will exhibit under specific conditions” (Wiegers & Beatty, 2013, p. 599). There are different formats for writing functional requirements such as the given-when-then format, user stories, and use cases. User stories are used in Agile software development. The given-when-then format is used for writing user story acceptance criteria. A set of acceptance criteria is used to determine whether a user story has been completed (Definition of Done).

A nonfunctional requirement is “a description of a property or characteristic that a system must exhibit or a constraint that it must respect” (Wiegers & Beatty, 2013, p. 600). Quality attributes are words for describing “a service or performance characteristic of software” (Wiegers & Beatty, 2013, p. 601).

There are standards for what makes a good requirement, such as being correct, unambiguous, complete, consistent, ranked for importance and/or stability, verifiable, modifiable, and traceable. INVEST is an acronym for remembering standards for good user stories: independent, negotiable, valuable, estimable, small, and testable.

An SRS can contain both nonfunctional and functional requirements.

References

Agile Alliance. (n.d.). What is “given – when – then”? https://www.agilealliance.org/glossary/gwt/

CEAP. Conservation Effects Assessment Project. (2006). System requirements specification for STEWARDS. US Department of Agriculture, Agricultural Research Service. https://www.nrcs.usda.gov/publications/ceap-watershed-2006-stewards-design.pdf

Cohn, M. (2004). Example user stories. Mountain Goat Software. https://www.mountaingoatsoftware.com/uploads/documents/example-user-stories.pdf

Eaker, F. (2006, November). Software requirements specification. Vyasa. https://vyasa.sourceforge.net/vyasa_software_requirements_specification.pdf

Hanington, B. M., & Martin, B. (2019). Universal Methods of Design: 125 ways to research complex problems, develop innovative ideas, and design effective solutions. Rockport Publishers.

Hedberg, T., Helu, M., & Newrock, M. (2017, December). Software requirements specification to distribute manufacturing data. NIST Advanced Manufacturing Series 300-2. National Institute of Standards and Technology. https://nvlpubs.nist.gov/nistpubs/ams/NIST.AMS.300-2.pdf

OpenVIBE. (2018, April). Inria Innovation Lab Certivibe v 1.0 software requirement specification. http://openvibe.inria.fr/openvibe/wp-content/uploads/2018/04/CERT-Software-Requirement-Specification.pdf

@ShitUserStory. (n.d.). Shit User Story. Twitter. https://twitter.com/shituserstory

Spyridonos, P. (2010, February 6). Software requirements specification for PDF split and merge requirements for version 2.1.0. University of Kentucky Software Verification and Validation Lab. https://selab.netlab.uky.edu/~ashlee/cs617/project2/PDFSam.pdf

 Texas Department of Information Resources. (2008, January 14). Software requirements specification instructions. https://dir.texas.gov/sites/default/files/Requirements%20Traceability%20Matrix%20Instructions.pdf

US General Services Administration. (2014, January). USDA personas and use cases. https://s3.amazonaws.com/digitalgov/_legacy-img/2014/01/Marsh-Personas.pdf

Wake, B. (2003, August 17). Invest in good stories, and Smart Tasks. XP123 Exploring Extreme Programming. https://xp123.com/articles/invest-in-good-stories-and-smart-tasks/

Wiegers, K., & Beatty, J. (2013). Software requirements (3rd ed.). Developer Best Practices Series. Microsoft Press.

Wikimedia Foundation. (2023, March 23). List of system quality attributes. https://en.wikipedia.org/wiki/List_of_system_quality_attributes