AoAD2 Practice: Customer Examples

Book cover for “The Art of Agile Development, Second Edition.”

Second Edition cover

This is a pre-release excerpt of The Art of Agile Development, Second Edition, to be published by O’Reilly in 2021. Visit the Second Edition home page for information about the open development process, additional excerpts, and more.

Your feedback is appreciated! To share your thoughts, join the AoAD2 open review mailing list.

This excerpt is copyright 2007, 2020, 2021 by James Shore and Shane Warden. Although you are welcome to share this link, do not distribute or republish the content without James Shore’s express written permission.

Revised: July 14, 2021

Customer Examples

Customers, Whole Team

We implement tricky details correctly.

Some software is straightforward: just another UI on top of yet another database. But often, the software that’s most valuable is the software that involves specialized expertise.

Ubiquitous Language
Whole Team
Real Customer Involvement

This specialized expertise, or domain knowledge, is full of details that are hard to understand and easy to get wrong. To communicate these details, use customer examples: concrete examples illustrating domain rules. Customer examples go hand-in-hand with ubiquitous language, which is a way of unifying the language used by programmers, domain experts, and the code itself.

To create customer examples, you’ll need people with domain expertise. Ideally, they’re part of your team. If not, you’ll have to go find them.

Your team might include people who have developed a layperson’s understanding of the domain. Programmers, testers, and business analysts often fall into this category. They may be able to create customer examples themselves. Even so, it’s a good idea to review those examples with real experts. There can be tricky details that a layperson will get wrong.

To create and use the examples, follow the Describe, Demonstrate, Develop process.


Task Planning

During task planning, look at the stories and decide whether there are any details that developers might misunderstand. Add tasks for creating examples of those details. You don’t need examples for everything: just the tricky details. Customer examples are for communication, not for proving that the software works.

For example, if one of your stories is “Allow invoice deleting,” you don’t need an example of deleting an invoice. Developers already understand what it means to delete something. However, you might need examples that show when it’s okay to delete an invoice, particularly if there are complicated rules to ensure that invoices aren’t deleted inappropriately.

If you’re not sure what developers might misunderstand, ask them! But error on the side of providing too many examples, at least at first. When domain experts and developers first sit down to create examples, both groups are often surprised by the extent of existing misunderstandings.

When it’s time to work on the examples, gather the team around a whiteboard, or shared document, if the team is remote. The whole team can participate. At a minimum, include a domain expert, all the programmers, and all the testers. They all need to be able to understand the details so they can share ownership. (See “Key Idea: Collective Ownership” on page XX.)

The domain expert starts by summarizing the story and the rules involved. Be brief: this is just an overview. Save details for the examples. For example, a discussion of invoice deletion might go like this:

Expert: One of our stories is to add support for deleting invoices. In addition to the UI mock-ups we gave you, we thought some customer examples would be a good idea. Deleting invoices isn’t as simple as it appears because we have to maintain an audit trail.

There are a bunch of rules around this issue. In general, it’s okay to delete invoices that haven’t been sent to customers, so people can delete mistakes. But once an invoice has been sent to a customer, it can only be deleted by a manager. Even then, we have to save a copy for auditing purposes.

Ubiquitous Language

If the team is just starting to learn about the domain, a more detailed conversation might be required. In that case, consider creating a ubiquitous language.


Make rules concrete by providing examples.

Once the domain expert has provided an overview, resist the temptation to have them keep describing rules. Instead, make the rules concrete by asking for examples. Literally asking, “Can you give me an example of that?” will help get the ball rolling.

Participants can also get the ball rolling by proposing an example, but try to get the domain expert to take the lead. One trick is to make a deliberate mistake and allow the domain expert to correct you.1

1I learned this trick from Ward Cunningham. A variant was later popularized by Steven McGeady as Cunningham’s Law: “The best way to get an answer on the Internet is not to ask a question; it’s to post the wrong answer.”

Tables are often the most natural way to provide examples, but you don’t need to worry about formatting. Just get examples on the whiteboard or shared document. The scenario might continue like this:

Programmer: So if an invoice hasn’t been sent, an account rep can delete the invoice, and if it has been sent, they can’t. (Picks up a marker and writes on whiteboard.)

UserSentCan delete?
Account RepNY
Account RepYN

Expert: That’s right.

Programmer (deliberately getting it wrong): But a CSR can.

UserSentCan delete?
Account RepNY
Account RepYN

Expert: No, a CSR can’t, but a manager can. (Programmer hands marker to expert).

UserSentCan delete?
Account RepNY
Account RepYN
ManagerYY, but audited

Tester: What about a CSR supervisor? Or an admin?

Expert: CSR supervisors don’t count as managers, but admins do. But even admins leave an audit trail.

UserSentCan delete?
Account RepNY
Account RepYN
ManagerYY, but audited
CSR SupervisorYN
AdminYY, but audited

Expert: To add another wrinkle, “sent” actually means anything that could have resulted in a customer seeing the invoice, regardless of whether they actually did.

Exported as PDF
Exported to URL

Tester: What about previews?

Expert: Nobody’s ever asked me that before. Well, obviously... um... okay, let me get back to you on that.

This conversation continues until all the details have been worked out, with programmers and testers asking questions to fill in gaps. Expect there to be some questions that customers haven’t considered before. If you use a ubiquitous language, sketch out the relevant part of your model and revise it as you go.

As you dig into the details, be sure to continue creating specific examples. It’s tempting to talk in generalities, such as “Anyone can delete invoices that haven’t been sent,” but it’s better to create concrete examples, such as “An account rep can delete an invoice that hasn’t been sent.” This will help expose gaps in people’s thinking.

You may discover that you have more to discuss than you realized. The act of creating specific examples often reveals scenarios customers hadn’t considered. Testers are particularly good at finding these gaps. If you have a lot to discuss, consider splitting up so programmers can start implementing while customers and testers chase down additional examples.


When the conversation is over, record the results for future reference. A photo of the whiteboard is often enough.

Test-Driven Development

The customer examples often represent some of the most important logic in your application. Be sure to document them. My preferred approach is to create automated tests. Rather than blindly copy every example into a corresponding test, though, I use the examples as inspiration for more carefully thought-out tests than can act as documentation for other programmers. To do so, I print out a copy of the examples and use test-driven development to build my tests and code incrementally. As I write each test and corresponding code, I check off the examples that the test covers.

This is easiest if you have a ubiquitous language and domain model. For example, your domain model might include an Invoice class with a canDelete() method. In that case, it might have tests such as “allows anyone to delete invoices that haven’t been sent” and “only allows managers to delete invoices that have been sent.”

As developers work on the code, the rigor code requires is likely to reveal some edge cases that weren’t part of the original discussion. It’s okay to go back to the whiteboard. It’s also okay to just ask a question, get an answer, and code it up. Either way, update the tests or other documentation.


Should we create examples prior to starting development on a story?

The Planning Game
Incremental Requirements

It shouldn’t be necessary. Creating examples can usually be your first development task. If you need to explore a few examples during the planning game in order to size a story, you can, but you don’t need to do so in general. Remember that requirements, including customer examples, should be developed incrementally, along with the rest of your software.


Many stories are straightforward enough they don’t need customer examples. Don’t try to force them where they’re not needed.

When you do need customer examples, you also need domain expertise. If you don’t have any experts on your team, you’ll need to make an extra effort to involve them.


When your team uses customer examples well:

  • Your software has few, if any, domain logic bugs.

  • Your team discusses domain rules in concrete, unambiguous terms.

  • Your team often discovers and accounts for special-case domain rules nobody had considered.

Alternatives and Experiments

Some teams like to use natural-language test automation tools, such as Cucumber, to turn customer examples into automated tests. I used to be one of them—Ward Cunningham’s Framework for Integrated Test (Fit) was the first such tool in the Agile community, and I was heavily involved with it.

But, over time, I realized that the value of the examples was in the whiteboard conversation, not the automation. In theory, customers would help write Fit tests, and use Fit‘s output to gain confidence in the team’s progress. In practice, that rarely happened, and didn’t have much additional value. Regular test-driven development was an easier way to automate and worked just as well. The same is true for tools such as Cucumber.

Cucumber stems from the behavior-driven development (BDD) community, founded by Daniel Terhorst-North, which has long been a strong proponent of customer collaboration. Although I don’t think tools such as Cucumber are necessary, the BDD community is also a good source of ideas for experiments. One such idea is example mapping, a way of collecting examples that uses index cards. [Wynne 2015]

You’re welcome to explore other options for creating customer examples, too. Some people do find tools such as Cucumber useful for structuring their communication, and some teams have used them to streamline audits and other third-party validation. Try the simple, collaborative, whiteboard-based approach several times, first, so you have a baseline to compare against. When you do experiment with other options, remember that customer examples are a tool for collaboration and feedback, not automation or testing. Be sure that your experiments enhance that core principle rather than detracting from it.

Further Reading

XXX Consider Gojko Adzic’s "Specification by Example"

XXX Consider Ken Pugh's Lean-Agile Acceptance Test-Driven Development: Better Software through Collaboration

Share your feedback about this excerpt on the AoAD2 mailing list! Sign up here.

For more excerpts from the book, or to get a copy of the Early Release, see the Second Edition home page.

If you liked this entry, check out my best writing and presentations, and consider subscribing to updates by email or RSS.