Crafting Testable Functional Requirements

The Qualities of an Effective Requirement

Before we start writing, we need to understand what "good" looks like. A poorly written requirement is ambiguous, leading developers to make incorrect assumptions. A well-written one is a clear contract that can be built and tested against.

To explore the characteristics of a high-quality requirement, watch this short video. The presenter calls them "bulletproof" requirements.

As the video explained, a great requirement has several key attributes. Let's summarize and group them into what are often called the SMART criteria, plus a few others:

• Specific & Unambiguous: It should be interpreted in only one way.
• Measurable & Testable: You must be able to verify that the requirement has been met. If you can't write a test case for it, it's not a good requirement.
• Achievable & Feasible: The requirement must be possible to implement with the available resources and technology.
• Relevant: It must align with a specific business objective.
• Time-bound: (More for projects, but for requirements, it means it's clear when it applies).
• Atomic: It should describe a single, discrete piece of functionality. Avoid using words like "and" or "or" that bundle multiple requirements together.
• Complete: All necessary information should be present.

One of the most common pitfalls is writing requirements that describe how to build something, rather than what the system needs to do. This trespasses on the role of the solution architect or developer.

For practical advice on maintaining this separation and using precise language, the following resource is excellent.

Standard Templates for Writing Requirements

Now that we know the "what" and "why," let's focus on the "how." Using standard templates brings consistency and clarity to your documentation. We will cover two common approaches: traditional formal statements and the more modern user story format.

1. Formal Requirement Statements

In formal documents like an FSD or SRS, requirements are often written as declarative statements. The language used is very important. Words like "shall," "will," and "should" have specific meanings.

In short:

• SHALL indicates a mandatory, verifiable requirement. This is the most common word for functional requirements.
• MUST is also mandatory but often used for non-functional requirements (like performance).
• WILL indicates a statement of fact or a future certainty.
• SHOULD indicates a goal or recommendation, not a binding requirement.

To structure these statements, a syntax called EARS (Easy Approach to Requirements Syntax) is very effective. It provides patterns for different types of requirements.

Here's an example of an Event-Driven requirement using EARS:

WHEN the user clicks the 'Export' button, the system shall generate a CSV file of the campaign performance data.

2. User Stories and Acceptance Criteria

In Agile environments, the most common format for a functional requirement is a User Story. It's a simple, user-centric template that captures the "who, what, and why."

A user story follows this structure:
As a , I want , so that .

Example:

As an advertiser, I want to see the total spend for my active campaigns on the main dashboard, so that I can quickly assess my daily budget consumption.

A user story on its own is not enough. It must be accompanied by Acceptance Criteria (AC), which are the specific, testable conditions that must be met for the story to be considered "done." This is where you make the requirement testable.

A popular format for writing ACs is Gherkin, which uses a Given-When-Then structure.

Here's how we could write ACs in Gherkin for our user story example:

Scenario: Displaying total campaign spend

Given I am logged in as an advertiser with active campaigns,
When I navigate to the main dashboard,
Then the system shall display a metric titled "Total Daily Spend".
And this metric shall be the sum of the 'spend' field for all campaigns with a status of 'Active'.
And the value shall be updated within 5 minutes of the last reported spend.

A Detailed Look at Documenting a Requirement

We've learned the theory and seen simple templates. Now, let's see how a complex functional requirement is fully documented within an FSD, combining many of the elements we've discussed. In the previous lesson, you saw the overall structure of an FSD; this video shows the deep level of detail for a single feature.

This comprehensive template is excellent for capturing complex functionality. For simpler requirements, a user story with clear acceptance criteria might be sufficient. The key is choosing the right level of detail for the situation.

Practice Exercise: From Vague Request to Testable Requirement

Now it's your turn to apply what you've learned. Your task is to transform a vague business request into a clear, concise, and testable functional requirement.

Scenario: You are a BA working on a programmatic advertising platform. A product manager tells you: "Advertisers need to be able to set budgets for their campaigns."

Here is a diagram of the typical AdTech ecosystem for context. The advertiser interacts with a Demand-Side Platform (DSP) to manage their campaigns.

Your Task:
Rewrite the vague request "Advertisers need to be able to set budgets for their campaigns" as a formal, testable functional requirement. Choose one of the following formats:

1. A User Story with at least two Acceptance Criteria written in Gherkin format (Given/When/Then).
2. An Event-Driven requirement using the EARS syntax (WHEN... the system shall...).

Think about the "weak words" to avoid. What specifics are needed? (e.g., What kind of budget? Daily? Lifetime? What are the constraints?)

Conclusion

In this lesson, we moved from understanding the structure of an FSD to mastering the craft of writing its most critical content: the functional requirements. You learned that telling the development team what to do requires precision, clarity, and a commitment to testability.

Key Takeaways:

• Effective functional requirements are SMART: Specific, Measurable, Achievable, Relevant, and Time-bound. They are also atomic and unambiguous.
• Always focus on the WHAT (the system's external behavior), not the HOW (the internal implementation).
• Use standard templates to ensure consistency and completeness. The main formats are:
  • Formal Statements: Using keywords like SHALL and patterns like EARS.
  • User Stories: Using the As a..., I want..., so that... format, always supported by specific, testable Acceptance Criteria (often in Gherkin's Given/When/Then format).
• The level of detail depends on the complexity of the feature and the needs of your team.

Preview of the Next Lesson:
We've thoroughly covered what the system must do. But how well must it do it? In our next lesson, we will address this by learning how to document key non-functional requirements (e.g., performance, security, usability). These quality attributes are just as critical to a project's success as the functional features.