Chapter 3: What is an Example?
Introduces the chapter’s questions about whether examples can specify a story and how many examples are needed, while previewing the topics to come.
After this chapter you will be able to
- Three parts of an example. Describe an example in terms of its context, action, and outcome, including what each part says about the system.
- Concrete examples and rules. Distinguish a generic rule from a concrete example, and explain why concrete does not always mean using literal values.
- Essential Data in Examples. Explain why an example should include only the concrete data needed to illustrate its rule, even when the system needs much more context to operate.
- Boundary example and its limits. Explain how the waiting-for-pickup example would expose a missing equals sign in the condition, and why the two examples do not guarantee that every programming mistake will be caught.
- Examples for shared understanding. Explain how examples in a requirements workshop help the business and development team reach a shared, unambiguous understanding of desired behavior, while also providing useful test cases later.
- Boundary between discovery and testing. Distinguish exploring examples to understand requirements from exhaustively exploring combinations for test coverage, and describe when a facilitator should redirect the workshop.
- Complementary rules and examples. Explain why examples cannot replace rules: rules state expected behavior concisely and abstractly, while examples make that behavior concrete and harder to misinterpret.
- Rule based story completeness. Explain how to decide whether a story has enough examples: agree on all its rules and illustrate each with a few examples that make it unambiguous, rather than aiming for a fixed total.
- Example focus versus rule use. Distinguish the rule an example focuses on from other rules it must satisfy. Explain how an address-change example can use a valid address while directing attention to whether the order has been picked up.
- Splitting multi-rule examples. Describe what to consider doing when one workshop example illustrates multiple rules, and how the concrete data needed may differ between the resulting examples.
What it builds on
- Collecting examples (chapter 2) · The collection of examples during structured conversations.
- Example Mapping in a nutshell (chapter 2) · Assumes familiarity with collecting examples around rules in Example Mapping.
- A useful meeting (chapter 2) · Assumes the requirements-workshop setting for collaborative discussion.
- Facilitation tips (chapter 2) · Facilitating a structured conversation.
- Start with a user story (chapter 1) · Starting BDD work with a user story.
Section by section
Introduction
Introduces the chapter’s questions about whether examples can specify a story and how many examples are needed, while previewing the topics to come.
3.1 How hard is concrete?
This section explains how to make an example concrete enough to illustrate system behavior unambiguously.
- Three parts of an example: Describe an example in terms of its context, action, and outcome, including what each part says about the system.
Why it matters: These three parts make clear what happened and how to tell whether the system behaved as expected. - Concrete examples and rules: Distinguish a generic rule from a concrete example, and explain why concrete does not always mean using literal values.
Why it matters: Unambiguous examples clarify what a general rule means in a particular situation. - Focus from concrete examples: Explain how concrete examples help a team notice problems in a proposed behavior.
Why it matters: A clear case can reveal conflicts that a broad statement leaves unnoticed.
Key terms: context, action, outcome, rule, concrete example, unambiguous, intention revealing concepts, concrete examples, unwanted side-effects, contradictions
3.2 Is all that concrete essential?
The section explains how to keep examples focused on the behavior they illustrate, while using workshops and optional AI assistance to develop them.
- Essential Data in Examples: Explain why an example should include only the concrete data needed to illustrate its rule, even when the system needs much more context to operate.
Why it matters: Relevant details make it easier to see what behavior an example is meant to clarify. - Workshop Detail Priorities: Describe the purpose of concrete examples in a requirements workshop and when inessential detail is removed.
Why it matters: The team can clarify the requirement without letting detail-polishing stall the workshop. - AI Example Review: Describe how an AI agent can support a facilitator in reviewing examples and why changes to its project-specific skill need team review.
Why it matters: AI can help spot problems during a busy discussion, while the team remains responsible for its conventions.
Key terms: example, single rule, concrete data, context, requirements workshop, concrete examples, formulate, scenario, facilitator, AI agent
3.3 Do we need more examples?
The section uses an address-change rule to show why an example at a boundary can catch an implementation mistake, while acknowledging that two examples cannot catch every mistake.
- Address change boundary: Explain when an order’s delivery address can be changed and how that differs from the team’s initial interpretation.
Why it matters: The exact boundary determines whether an address change should be allowed. - Boundary example and its limits: Explain how the waiting-for-pickup example would expose a missing equals sign in the condition, and why the two examples do not guarantee that every programming mistake will be caught.
Why it matters: A concrete boundary example can reveal a subtle coding error without providing exhaustive protection.
Key terms: waiting for pickup state, address change, concrete examples, waiting for pickup, <, <=
3.4 Why stop now?
This section explains why requirements workshops should gather enough examples to clarify desired behavior without turning into exhaustive test-design sessions.
- Examples for shared understanding: Explain how examples in a requirements workshop help the business and development team reach a shared, unambiguous understanding of desired behavior, while also providing useful test cases later.
Why it matters: Examples can prevent misunderstandings before they become code while remaining useful after delivery. - Boundary between discovery and testing: Distinguish exploring examples to understand requirements from exhaustively exploring combinations for test coverage, and describe when a facilitator should redirect the workshop.
Why it matters: Keeping exhaustive test design outside the workshop preserves attention for clarifying requirements. - Adjusting example counts: Describe how a team can improve its judgment about how many examples to collect.
Why it matters: Reviewing delivered stories helps the team refine its example gathering rather than rely on a fixed quota.
Key terms: discovery phase, requirements workshop, examples, desired behavior, software testing, good coverage, facilitator, product owner, right number of examples, retrospectives
3.5 Rules vs. examples
This section explains why a software specification needs both explicit rules and illustrative examples, and how rule coverage—not an example count—determines whether a story is specified.
- Complementary rules and examples: Explain why examples cannot replace rules: rules state expected behavior concisely and abstractly, while examples make that behavior concrete and harder to misinterpret.
Why it matters: Recording both lets the team see the general requirement and agree on what it means in specific cases. - Story rule and example roles: Describe how a stakeholder's goal becomes a story whose scope is defined by rules, with examples used to check the team's understanding and the rules' expression.
Why it matters: These distinct roles help a team check whether it has agreed on both the story's boundaries and its intended behavior. - Rule based story completeness: Explain how to decide whether a story has enough examples: agree on all its rules and illustrate each with a few examples that make it unambiguous, rather than aiming for a fixed total.
Why it matters: Checking each rule is more reliable than deciding a story is ready because it has an arbitrary number of scenarios.
Key terms: rules, examples, Specification by Example, user story, acceptance criteria, example mapping, story
3.6 My example illustrates multiple rules!
This section explains how to keep examples focused on one rule even when they depend on other rules, and where focused examples fit alongside other documentation.
- Example focus versus rule use: Distinguish the rule an example focuses on from other rules it must satisfy. Explain how an address-change example can use a valid address while directing attention to whether the order has been picked up.
Why it matters: It lets the team use realistic examples without treating every rule they rely on as the point of the example. - Splitting multi-rule examples: Describe what to consider doing when one workshop example illustrates multiple rules, and how the concrete data needed may differ between the resulting examples.
Why it matters: Separating the examples makes each rule easier to discuss without carrying along irrelevant detail. - Relative detail of examples: Explain how the section distinguishes a rule from an example when a statement falls between obviously abstract and obviously detailed.
Why it matters: It keeps borderline labels from distracting the team from whether an example clarifies its rule. - Limits of focused examples: Explain what short, focused examples show well and why the section also names other forms of documentation.
Why it matters: A team can keep rule examples focused without expecting them to serve as its only view of the system.
Key terms: rule, example, focus, utilize, order state, valid address, requirements workshops, examples, rules, concrete data
3.7 Summary
Where this is used later
- The principles (chapter 7) · The earlier discussion of concrete examples.
- Document the essence of the behavior (chapter 7) · Supports documenting the essence of a behavior when formulating scenarios.
- (chapter intro) (chapter 6) · Provides the distinction between discovering examples in a workshop and later formulating them as scenarios.
- Discovery (chapter 4) · The distinction between discovery and later testing informs the discussion of discovery work.
- Shared understanding (chapter 6) · Shared understanding depends on communicating expected behavior clearly.
- Scenario granularity (chapter 6) · The distinction between rules and examples.
- The old scenario (chapter 7) · The distinction between rules and examples.
- Illustrative scenarios (chapter 7) · The distinction between rules and examples.
Concepts explained in this chapter
- exampleA concrete instance illustrating an expected behavior or a possible outcome of a rule.
- business ruleA business constraint governing payment when a customer collects an order.
- contextThe state or conditions established before an action takes place in an example.
- concrete dataConcrete values representing the entities, states, or inputs involved in a scenario rather than abstract placeholders or general description.
- requirementsA requirement is a statement of a stakeholder need, constraint, or expected system behavior that guides solution development.
- shared understandingA common interpretation of requirements and expected behavior held by the members of a team.
- resultAn outcome is a description of the system state after the behavior of interest has taken place in an example.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
