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.

Customer Examples

Audience
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.

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.

Ally
Whole Team
Real Customer Involvement

To create customer examples, you’ll need to talk to people with domain expertise. Ideally, you have people with those skills as 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.

Describe

Ally
Task Planning
Customer examples are for communication.

During task planning, look at your stories and decide whether there are any details that developers might misunderstand. Add tasks for creating examples of those details. You don’t need to provide 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 to provide 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 you’re ready 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, you’ll need a domain expert, all the programmers, and all the testers. They all need to be able to understand the details so they can work on them when needed. (See “Key Idea: Collective Ownership”.)

Start 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.

Demonstrate

Make rules concrete by providing examples.

Once you’ve provided an overview, resist the temptation to keep describing rules. Instead, make the rules concrete by providing examples. Developers, you can 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
CSRNY
CSRYY

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

UserSentCan delete?
Account RepNY
Account RepYN
CSRNY
CSRYN
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
CSRNY
CSRYN
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.

“Sent”
Emailed
Printed
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 relevant 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.

As you dig into the details, 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.

Develop

When you’ve fleshed out the details, record the results for future reference. A simple photo of the whiteboard is often enough.

Ally
Test-Driven Development

The customer examples often represent some of the most important logic in your application. Be sure to document it. 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.

As you develop, the rigor required by code is likely to reveal some more edge cases you hadn’t considered. 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 your tests or other documentation.

Questions

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

Allies
The Planning Game
Incremental Requirements

It shouldn’t be necessary. 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.

Prerequisites

Many stories are straightforward enough that 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.

Indicators

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. 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 distracting from it.

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.