EBOOK

Best Practices Guide

for Writing Requirements
 Table of Contents

INTRODUCTION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 03

COMMON CHALLENGES OF WRITING REQUIREMENTS . . . . . . . . 04

OVERCOMING CHALLENGES IN WRITING REQUIREMENTS. . . . . 08

IMPROVING THE QUALITY OF YOUR REQUIREMENTS. . . . . . . . . . 18

TEMPLATES FOR WRITING EFFECTIVE REQUIREMENTS. . . . . . . . 23

jamasoftware.com Best Practices Guide for Writing Requirements | 2

 Introduction
Development teams face many challenges in today’s competitive, fast-paced market.
In this eBook, we’ll explore how to navigate a path from a high-level market need or
problem to a detailed requirement for an actual product, system, or software. We’ll cover
best practices for writing requirements in depth and demonstrate how to write those
requirements in a manner such that all stakeholders have a clear understanding of the
needs around the development of any complex system, software, or product.

WHY EFFECTIVE REQUIREMENTS MATTER

Better requirements lead to clearer, more effective communication between stakeholders.

This drives the entire organization toward greater transparency, less rework, and,
accelerated development… without sacrificing quality. While writing requirements is both
an art and a science that will vary by context, there are a few best practices to consider.

In an ideal world, every individual user, business, and functional requirement would exhibit the
following qualities: complete, correct, feasible, necessary, prioritized, unambiguous, verifiable,
consistent, modifiable, and traceable. We’ll dive deeper into these qualities later in this eBook.

jamasoftware.com Best Practices Guide for Writing Requirements | 3

1 Common Challenges
of Writing Requirements
CHAPTER 1 | Common Challenges of Writing Requirements

Common The designer/customer

Challenge disconnect
# 1 The first common challenge organizations face when writing requirements is that
designers aren’t exactly sure what they’re supposed to deliver and what the actual
end user needs. From the perspective of a designer, the detail that a product
marketer or a customer can provide is sometimes insufficient, and many questions
remain unanswered. The designers either go on to build something that doesn’t
result in a successful outcome, or they ask a series of questions to which the product
marketer doesn’t have clear answers.

jamasoftware.com Best Practices Guide for Writing Requirements | 5

CHAPTER 1 | Common Challenges of Writing Requirements

Common Too many details,

Challenge too little innovation
# 2 The second common challenge organizations face when writing requirements is
the opposite of the first problem. Teams are given very granular details that over
constrain them. In this scenario, designers have little freedom to innovate. This often
takes the form of specs from a previous product that you’re reusing, or a customer
RFP, where customer requirements are highly detailed. And while at times this is
necessary, it doesn’t often lead to innovation. Designers often end up in a
pattern of just doing what they’re told in this scenario, instead of thinking
about how they could creatively solve a problem.

jamasoftware.com Best Practices Guide for Writing Requirements | 6

CHAPTER 1 | Common Challenges of Writing Requirements

Common Right requirement,

Challenge wrong product
# 3 The third common challenge organizations face is where the team builds a product,
but it just simply doesn’t meet the original requirements. The team may have
done well in gathering the problem statement and figuring out the constraints, but
inevitably the product somehow drifts outside of what they were originally trying to
solve. As design challenges come up, trade-offs are made, and the specifications
related to the product slowly drift outside of the scope of an “acceptable” product.
In this scenario, the team is so focused on building ‘something’, they end up not
building the right ‘something’.

jamasoftware.com Best Practices Guide for Writing Requirements | 7

2 Overcoming Challenges
in Writing Requirements
CHAPTER 2 | Overcoming Challenges in Writing Requirements

Understanding the Problem

You’re Trying to Solve
Clearly defining the problem is key to day may have been a faster horse or a horse
aligning all stakeholders. So, creating that didn’t require as much food. And while
problem statements is a great first step in those are important requests, they usually
understanding the context of who you’re don’t lead to innovation—like the invention of
trying to help, what problem they have, and the automobile. The Five Whys
how often it occurs.
Interestingly, the problem that Henry Ford A great way to distill
This statement gives the team context so solved was not inventing the automobile the problem your trying
when they do get into the weeds of detailed (as it had already been invented), he solved to solve is by using the
requirements gathering, they’re able to trace the affordability problem. The problem he “Five Whys” method.
it back to the original problem or the need identified (and solved) was that the high cost The theory here, is that
that you’re trying to fulfill. of acquisition prohibited most people from if you ask “Why?” five
owning one. Henry Ford made automobiles times, you’ll eventually
Legend has it that Henry Ford may have
accessible to more people by revolutionizing get to the root cause
once said, “If I had asked people what they
the way they were built and bringing down of the problem.
wanted, they would have said faster horses.”
the cost. And this was made possible by truly
This quote aptly demonstrates how understanding the problem that they were
stakeholder needs and problem statements trying to solve before they set out to solve it.
are not the same thing as customer
requirements or feature requests. A
customer feature request in Henry Ford’s

jamasoftware.com Best Practices Guide for Writing Requirements | 9

CHAPTER 2 | Overcoming Challenges in Writing Requirements

Defining Your Requirements

Hierarchy and Taxonomy
Once you’ve clearly defined the problem, you need to now break it down into more granular
needs or requirements. This may take many different forms, like a products requirements document (PRD),
a requirements spec, a very long Excel sheet, or a database of requirements.

In order to improve requirements management as a whole, your teams must establish a clear hierarchy and taxonomy.
It’s important that teams understand the difference between requirements and design as it’s often something people get
confused about.

Problem / Stakeholder Need

Requirements:
A requirement should communicate
what the product, system, or software Requirements

needs to do. The requirements are the Product Concept

tool that we use to identify the right

product to build, and ensure we’re
Design Specifications
building it in the right way.

jamasoftware.com Best Practices Guide for Writing Requirements | 10

CHAPTER 2 | Overcoming Challenges in Writing Requirements

Design:
The design specification, on the other hand, is the response to the
requirements and should indicate what the product, system, or software
does. Specifications are not useful to identify the right product to build,
but they are useful to communicate what the product is and how it works.

This delineation is important because using traditional design EBOOK

specifications as requirements can lead to a lot of problems, like over The Jama Software Guide to
constrained designers. The goal is to capture the needs of the products, Requirements Traceability highlights
system, or software users and customers without constraining or the importance of tracing requirements
specifying design. without the headaches and risks of a
traceability matrix in Excel, but also
how to do so in a way that sets your
organization up for future success.
Learn how traceability helps teams:
EXAMPLES:
• Accurately assess the impact
Poorly worded requirements with design embedded in the statement:
of changes
The software algorithm will take two audio signals, each of 100dB
dynamic range, and combines them into a single output signal with at • Track the full history of product
development
least 140dB dynamic range so that we can save power.
• Keep everyone in sync
Well written requirement that demonstrates need without constraining
design: The solution shall consume less than 20mA while in operation • Consistently improve the quality of
the products being built
which is below industry standard of competing devices.

jamasoftware.com Best Practices Guide for Writing Requirements | 11

CHAPTER 2 | Overcoming Challenges in Writing Requirements

It’s important to come up with a taxonomy of your traceability and your hierarchy.
Here are a few examples:

Problem / Stakeholder Need

Requirements
Product Concept

Design Specifications

This is a very basic example where you have your problem or your stakeholder need. That decomposes
down to requirements, and the blue boxes relate more to the design. Once you’ve defined the problem
or stakeholder need, you might start coming up with a conceptual product or a concept of operations
(CONOPS). Whereas from the requirements perspective, you would then be able to start creating actual
design specifications from those requirements.

jamasoftware.com Best Practices Guide for Writing Requirements | 12

CHAPTER 2 | Overcoming Challenges in Writing Requirements

Agile

Feature

User Story
Product Architecture

Code

You can also look at this in Agile terms. You might author a list of features or epics that you want to
decompose down into user stories. The same principles apply but the semantics may be different. The
process of how and when you do this documentation may also differ.

jamasoftware.com Best Practices Guide for Writing Requirements | 13

CHAPTER 2 | Overcoming Challenges in Writing Requirements

Scaled Agile
Strategic Themes

Epics

Business Case

Feature Feature

Design / Architecture Design / Architecture

User Story User Story User Story User Story

Code Task Code Task

Again, if your team is using the Agile methodology instead of defining everything up front, you may experiment
and build up your documentation of requirements through several iterations and feedback loops. Often, when
making products or systems that are extremely complex, they don’t easily fit into a two-level construct. In that
case, you would build more layers into the traceability. In this example, we demonstrate strategic themes going
down to epics, which decompose into features and user stories. You may notice that there are two branches on
either side. That might represent two different modules or subsystems that are living independently but may be
interconnected up to that higher-level solution that you’re implementing.

jamasoftware.com Best Practices Guide for Writing Requirements | 14

CHAPTER 2 | Overcoming Challenges in Writing Requirements

Complex Regulated System

Stakeholder Needs

System Requirements

System Architecture

HW Requirements SW Requirements

HW Architecture SW Architecture

Block Req Block Req Unit Req Unit Req

Design Design Design Design

We can also look at this with a system engineering perspective for a complex regulated system. Teams who are
building life-critical applications or products, for example, are given a very specific method to follow by regulatory
bodies. In this case, if teams miss a requirement, or don’t properly design and test it, it could lead to the loss of
life. Traceability is critical to building safety-critical products like airplanes or cars. You must then determine what
taxonomy best fits with the product you’re building—keeping in mind that the industry that you’re building in is
also very important.

jamasoftware.com Best Practices Guide for Writing Requirements | 15

“
Through Jama, we have been able
to fully document our functional
and technical requirements for
multiple products/projects. For
any project in which you need to
document detailed requirements,
especially software development,
Jama would be well suited for use.”

Thai Trinh, Senior Business Analyst

IT & Services Company
CHAPTER 2 | Overcoming Challenges in Writing Requirements

Bridge the Communication

Gap with Traceability
Irrespective of your industry or your requirements management tool. This
methodology, it’s important to clearly define glossary should define what each of these
the requirements traceability and differentiate levels mean and who’s responsible for the
between requirements and design. Because process and outcomes. When you establish
oftentimes, a semblance of a model exists, but traceability at requirement levels, you’re able
people on different teams are using different to decompose the needs into more granular
terms referring to the same thing. details and demonstrate where you have
verification and validation coverage.
It’s critical to be clear on the semantics and
have a glossary to define what each of these Establishing traceability allows you to separate
levels mean. This should be in both your documenting the need from documenting
requirements management plan and your the solution.

Embracing Change
If you’re using Agile methodology and iterating often, it’s important to be able to change
course very quickly and very often. You’ll need to be able to see the ripple effects of changing a
higher-level epic, and what user stories or tests will be impacted. Traceability makes you quicker
and faster down the line when you’re ready to develop these products.
To learn more about the importance of tracing requirements without the headaches and risks of a traceability matrix in Excel, but
also how to do so in a way that sets your organization up for future success. Download this free eBook, “The Jama Software Guide
to Requirements Traceability”

jamasoftware.com Best Practices Guide for Writing Requirements | 17

3 Improving the Quality
of Your Requirements
CHAPTER 4 | Improving the Quality of Your Requirements

The “golden rule” of requirements authoring is that

you must have clear and effective communication
with your stakeholders. If someone new to your
company picks up a requirement document, are
they going to be able to understand what the
requirement is and what the requirement means?

You must also have clear and open communication

with your stakeholders. You may have a perfectly EBOOK
written set of requirements, but if you aren’t sharing Requirements are the foundation of a smooth-running
and collaborating that requirement with your process and are the essential inputs to your mission-
colleagues, you’re going to run into problems. The critical projects. Effectively managing the flow of
teams that are going to take your requirements changes and refinements early in your lifecycle will
significantly reduce both quality issues downstream
and turn them into a designed solution need to
and the volatility that plagues so many projects.
be part of that process. Below we have provided
recommendations – not hard rules – for writing Download our free eBook Best Practices Guide to
requirements. Use these as guidelines but Requirements and Requirements Management to
you’ll want to tailor them to your organization’s learn more about:
specific and unique needs - because well written
• The business value of better requirements
requirements require a mix of both science and art.
• The four fundamentals of requirements
management

• Finding the right level of detail in requirements

jamasoftware.com Best Practices Guide for Writing Requirements | 19

CHAPTER 4 | Improving the Quality of Your Requirements

Characteristics of
Effective Requirements
Necessary Unambiguous
Each requirement should be necessary Each requirement should be simple,
or required. concise, and clearly defined.

• Each requirement should document a • All readers of a requirement statement

capability that the stakeholders really need should arrive at a single, consistent
or one that’s required for conformance to an interpretation of it, but natural language is
external system requirement or a standard. highly prone to ambiguity. Write requirements
in simple, concise, straightforward language
• Every requirement should originate from
appropriate to the user domain. Define all
a source that has the authority to specify
specialized terms and those that might confuse
requirements. Trace each requirement back
readers in a glossary.
to specific voice-of-the-customer input, such
as a problem statement, stakeholder need, or
industry standard.
EXAMPLE:

Ambiguous: ”The car shall be blue”

Unambigious: “The car shall be sky blue (#7BAFD4)”

jamasoftware.com Best Practices Guide for Writing Requirements | 20

CHAPTER 4 | Improving the Quality of Your Requirements

Feasible Verifiable
Each requirement must be possible to Each requirement should be measurable or testable.
implement.
• See whether you can devise a few tests or use other verification
• It must be possible to implement each approaches, such as inspection or demonstration, to determine
requirement within the known capabilities whether the product properly implements each requirement.
and limitations of the system and its operating
environment. • If a requirement isn’t verifiable, determining whether it was
correctly implemented becomes a matter of opinion, not objective
• To avoid specifying unattainable analysis. Requirements that are incomplete, inconsistent,
requirements, have a designer or developer infeasible, or ambiguous are also unverifiable.
work with marketing or the business analysts
throughout the elicitation process. • The key here is that you need to add a qualifying objective, or
you need to change this requirement statement to make it more
• The technical resource can provide a reality measurable or testable. It’s always a good idea to avoid adverbs,
check on what can and cannot be done also known as any word that ends with “ly.” Adverbs typically are
technically and what can be done only at not testable.
excessive cost.

• Incremental development approaches and

proof-of-concept prototypes are ways to EXAMPLE:
evaluate requirement feasibility.
Incorrect: “The car must run quickly”
Correct: “The car must be able to reach 100 mph in less
than 10 seconds”

jamasoftware.com Best Practices Guide for Writing Requirements | 21

CHAPTER 4 | Improving the Quality of Your Requirements

Correct
Each requirement must accurately describe the functionality to be built

• The reference for correctness is the source of the requirement, such as an actual user or a high-level
system requirement. A software requirement that conflicts with its parent system requirement is not correct.

• Only product users can determine the correctness of requirements, which is why users, or their close
surrogates should review the requirements.

Reviewing and Discussing Requirements

Reviewing and discussing requirements leads to a shared
understanding of what you’re setting out to build and why.

Taking time up-front to review needs & requirements:

• Gives you feedback and makes you a better author

• Increases shared understanding amongst team

• Helps define acceptance criteria and ensure testability

• Reduces surprises and missed requirements

jamasoftware.com Best Practices Guide for Writing Requirements | 22

4 Templates for Writing
Effective Requirements
CHAPTER 5 | Templates for Writing Effective Requirements

Requirement Templates

[ Trigger ] [ Precondition ] Actor Action [ Object ]

When a collision and the passenger the system SHALL detonate the passenger
is detected airbag switch is on airbags

Reason /
User Need Purpose Objective

As a driver I need to know my so that I can abide without losing vision

vehicle speed by traffic laws of the road

jamasoftware.com Best Practices Guide for Writing Requirements | 24

 Conclusion
Writing requirements and requirements management can appear to be a complex topic, but at its core,
it’s a simple concept. It helps teams answer the question: Does everyone—from business leaders to product
managers and project leaders to developers, QA managers and testers—understand what is being built and why?

When everyone is collaborating and has full context and visibility into the discussions, decisions, and changes involved
in product development, they maintain high quality and almost always ensure success.

To learn more about how Jama Software can help your team improve the quality of your requirements writing and
requirements management, get in touch with us today.

“You won’t learn how to write good requirements from reading a

book... You need practice. Constructive feedback from reviewers
can help anyone become a better writer. In fact, it’s essential.”

Karl Weigers, “Writing High Quality Requirements”

jamasoftware.com Best Practices Guide for Writing Requirements | 25

 ABOUT JAMA SOFTWARE

Jama Software provides the leading platform

for requirements, risk and test management.
With Jama ConnectTM, engineering teams
realize improved cycle times, increased quality,
improved time to compliance and faster time-
to-market. Jama has a growing customer base
of more than 600 organizations, across 30
countries, serving the following industries:
aerospace and defense, medical device
development, automotive, semiconductor,
software development, financial services and
insurance, and industrial manufacturing.

To learn more, visit

jamasoftware.com

jamasoftware.com Best Practices Guide for Writing Requirements | 26