specification by example workshop

1. SPECIFICATION BY EXAMPLE
Looking for the source of the truth

2. Specification by Example
• Key benefits:
– Less rework
– Higher product quality
– Implementing changes more efficiently
– Better alignment of the activities of different roles
• Key Practices:
– Deriving scope from goals
– Specify collaboratively
– Illustrating using examples
– Refining the specification
– Automation validation
– Evolving a living documentation system

3. Specification by example
• Understand better the goals of the system
• Building a living documentation of the system
• Maintaining a constant source of the truth
• Validating the system often in order to ensure
the functionality
• To describe the system in a way so that it is
easy to add features.

4. Deriving scope from goals
• F16 should fly at 2 to 2.5M (requirement)
• F16 should be able to scape from combat
(goal)
GOAL1
REQ1
REQ2
REQ3
GOAL2
Strategy
Needs
CompetitivenessSolution to
Implement:
A requirement use to be a direct
answer to a specific goal

5. Deriving scope from goals
• Ask for the goals using the requirements
• Be clear about the goals when the
requirements are defined.
• Refine your requirements in the context of the
goals not other requirements
• If you have any doubt, don’t be fooled, ask for
the right person .

6. Deriving scope from goals
• “The hardest single part of building a software
system is deciding precisely what to build.”
– Fred Brooks, The Mythical Man-Month: Essays on Software
Engineering (Addison-Wesley, 1975)
• “People tell you what they think they need, and by asking
them “Why” you can identify new implicit goals they have.
Many organizations aren’t able to specify their business goals
explicitly. However, once you derived the goals, you should
again reverse and derive scope from the identified goals,
potentially discarding the originally assumed scope.”
– Christian Hassa

7. Deriving scope from goals
Received scope
Adressesed goals
Derived scope
WHY DO YOU NEED THAT?
COLLABORATIVE SOLUTION
Challenging requirements is always part of the solution model

8. EXERCISE 1
• The system should persist my shopping cart
for 1-2 weeks
• The system should be able to send me a copy
of my shopping cart
• The system should alert if any of the prices
has changed in the articles of my shopping
cart.
• The shopping cart should appear always when
the user logs in.

9. Deriving scope from goals
• As Stakeholder (WHO)
• In order to achieve some goal (WHY)
• I need some system function (HOW)
Advice: Use this form for deriving
scope from goals

10. Specify collaboratively
• Different teams in different context have their
own way of collaborating.
– Find your own way!
– Discover how to make efficient conventions!
– Always look for improvements in your way!
• Of course I am talking about cross-functional-
teams.

11. Specify collaboratelly
“Specification workshops are intensive,
hands-on domain and scope exploration
exercises that ensure that the implementation
team, business stakeholders, and domain
experts build a consistent, shared understanding
of what the system should do”
– Gojko Adzic. “Specification by Example: How
Successful Teams Deliver the Right Software.”

12. EXERCISE 2
• Let’s make a kite.

13. Specify collaboratelly
• Workshop goals
– To find the technical constraints (feasibility)
– To find the business constraints (boundaries)
– To address the solution targets (goals)
– To build a common vocabulary
– To use the right examples for specifications
– To establish a safety network of knowledge and
later refinement.

14. Specify collaboratelly
• Prepare the workshop beforehand.
• Record the event for further referencing.
• Business use to drive but others can raise some insights.
• Clasify the topics:
– Not in scope
– To further investigation
– Not easy feasible
– High importance
• Outcome:
– write a document with some conclusions.
– Create a follow up agenda
– Next steps

15. Specify collaboratelly
• Smaller workshops (three amigos)
– A tester
– A developer
– A Business analyst
Outcome: Acceptance
Criteria Narratives

16. Be sensitive to your user task’s
“altitude”
16
© Jeff Patton, all rights reserved, www.AgileProductDesign.com
* from Cockburn’s Writing
Effective Use Cases
Functional or “Sea level”
I’d reasonably expect to complete this in a single sitting
Sub-Functional or “Fish level”
Small tasks that by themselves don’t mean much. I’ll do
several of these before I reach a functional level goal
Activity or “Kite level”
Longer term goals often with no precise ending. I’ll
perform several functional tasks in the context of an activity
Too abstract
Too detailed
Think about user
experience at this
level

17. Specify collaboratelly
• Find the right examples to illustrate a feature
• Use the examples as drivers in a specification
workshop
• Write out those examples for further
reference.
• Use the domain vocabulary around the
examples.
• Examples are easy to understand and share.

18. Specify collaboratelly
Refination meetings:
• Acceptance criteria write down. (peers)
• Acceptance criteria review. (seniors)
• Batching questions. (business)
• Key conversations  use your documentation tool for
collect it.
• Planning meetings. (testers, developers)
• Elephant Carpaccio & Story mapping
– http://agileproductdesign.com/writing/how_you_slice_it.pdf
– http://alistair.cockburn.us/Elephant+Carpaccio+Exercise

19. The user story map contains two
important anatomical features
• The backbone of the application is the list of
essential activities the application supports
• The walking skeleton is the software we build that
supports the least number of necessary tasks
across the full span of user experience
19
© Jeff Patton, all rights reserved, www.AgileProductDesign.com
time
necessity
The backbone
The walking skeleton

20. Given story map organized vertically by
necessity, we need only slice to plan
• Choose coherent groups of features that consider the span of business
functionality and user activities
• Support all necessary activities with the first release
• Improve activity support and add additional activities with subsequent
releases
20
© Jeff Patton, all rights reserved, www.AgileProductDesign.com
time
optionality
necessary
less
optional
more
optional
first release
second release
third release

21. Exercise 3
• Slice the shopping cart epic from user stories
to tasks
• Review it against another group (win to win)
• User story mapping to release the shopping
cart product incrementally
• Outcome: the final acceptance criteria for the
first release.

22. Illustrating using examples
• “Illustrating requirements using examples is a
way to specify how we expect the system to
work with enough detail that we can check
that assertion. Examples used to illustrate
requirements are good black-box tests.”
– Gojko Adzic. “Specification by Example: How
Successful Teams Deliver the Right Software.”

23. Illustrating using examples
• Examples spot inconsistencies
– Free delivery example
• Examples spot ambiguities
– Free for everyone!
• Examples helps to dive in the user story
– When to send an email?
• Examples shows boundaries
– Who is NOT able to receive this loan

24. Illustrating using examples
• Examples should be complete

25. Illustrating using examples
• Examples should be realistic
– Avoid making up data
– If possible use real data
– Extract examples from the organization
– Or clients!
I am not good as an example

26. Illustrating using examples
• Use examples for non functional requirements
– Performance targets should be precise
– Resiliency only has a meaning with examples
• Use examples to find the boundaries
– Technical exclusions
– Warning messages
– Actions after push to the limits
• Use mockups to illustrate your examples.

27. Illustrating using examples
• The paradigmatic example (example of
examples)
– https://en.wikipedia.org/wiki/Tests_of_general_re
lativity
• Good examples capture expectations and
business concepts.

28. Refining the specification
“In its rough form, a diamond is a lusterless,
translucent crystal that resembles a chip of
broken glass. For it to be transformed into a
jewel, it must be cut into a particular gem shape
and then polished, facet by facet.”
– Edward Jay Epstein, The Diamond Invention

29. Refining the specification
• From raw examples to Acceptance tests
• Focused, Precise and Testable
• About business functionality, not software
design
• Should document what the system does, no
more.
• Where were the S.M.A.R.T. requirements?
– Those are coming from Management by
Objectives – Peter Drucker 1.981

30. Refining the specification
• Free delivery example
• Bad examples are more frequent than good
ones
– Scripts are not specifications
– Technical oriented language is a bad sympton
– Describe what the system does not imply dense
user-system flow.
– But still should be executable.
– Merciless refination

31. Refining the specification
• Self exploratory
– Use Inputs and outputs as behaviour expectation
– Use a title and a description paragraph
– Specify the actor and the goal to achieve
– Try to understand it in the context of a regression
test fail.
– Ask another person if she understands the
specification.

32. Exercise 4
• The shopping basket revisited
– Refine our specification
– Add a new functionality

33. Refining the specification
• A good specification should contain tipically
– Key examples of each important part of the
business functionality.
– An example of each important technical edge case
or boundary conditions.
– An example of each particular troublesome area
of the expected implmentation.
• Over-specify has always a bad smell

34. Refining the specification
• Self-explanatory
• Use the domain language
• Use given-when-then narrative aka Gherkin
• Focused in a single aspect
• Do not try to over specify (refine instead)
• Use the happy path to enable the automation
pipeline.

35. Automating validation