Acceptance criteria, or AC, describe what a feature or bugfix does. Writing them is an art, and some AC work much better than others. So, how do we make them work? By including a little more detail.

Let’s explore the goals of AC, a standard example, an example that works better, a few counterarguments, and how to write great AC with ease.

Goals of AC: “Right Thing”, “Thing Right”, Documentation

What are the goals of AC? They should:

  • Help us build the “right thing”
  • Help us build the “thing right”
  • Document the thing

Build the “right thing” and building “thing right” are the goals of all software writing. More about that in a minute.

For documentation, I want as many people as possible to understand my work. This includes new hires, engineers, designers, PMs, team leads, and could even include executives.

But mainly, I want engineers to understand the work later. Tickets can be a rich artifact about how and why something was done in the past. But only when we write them well.

This is why AC matters!

Almost Enough Detail

Let’s look at a standard example of AC. It’s almost good enough, because it includes almost enough detail.

Consider this system: a technician running the scoreboard at a basketball game:

Given I shoot a basketball into the hoop
Then I see the points go up

Seems pretty straightforward! But in walks a team owner who doesn’t know about basketball. They start asking questions.

“Given I shoot a basketball into the hoop.” Which hoop: mine or the opponent’s? Do my points go up if I shoot it into my hoop?1

Shoot it from where? The points scored in a basketball game depend on the shooter’s position.

“Then I see the points go up.” How many points should it go up? If I shoot a free-throw, and my points go up by ten, is that acceptable?

Whose points go up? If I score and my opponent’s points go up, is that acceptable? What if they both go up?

Are these silly questions? Sure. But notice that each one could be true inside our AC. It isn’t quite specific enough.

A Little More Detail

Here’s a more robust version of this story. It has just a little more detail. Those details make it work better.

Given I'm standing outside the three-point line
When I shoot a basketball into my opponent's hoop
Then I see my team's points go up by three

These three sentences answer all our previous questions:

  • Which hoop? “My opponent’s.”
  • Shot from where? “Outside the three-point line.”
  • How many points should go on the board? “Three.”
  • For whom? “My team.”

We can add more details as needed.

Counterargument: It’s Fine!

Everyone knows what it means to shoot a basketball; what if the ticket is fine as it is? Undoubtedly, over-specification has a cost.

But what do we gain by adding a little more detail? The latter AC contains more information, so it changes how we talk about scope. It changes how we talk about implementation. It increases our chances of building the “right thing.” It precisely describes verification. And it provides less surface area for stakeholders to insert surprising criteria.

I think it’s worth it to find just a little more detail.

Counterargument: Where Does It Stop?

Where does it stop? Couldn’t we keep adding detail until the ticket is an overcooked mess?2

We could. Instead, we’ll find the line. There’s a reason to be explicit that the three-point line and three points go together, because getting that wrong has meaningful consequences in the system. A trivial detail, like the position of the referees on the court, can be omitted.

There’s a reasonable line; find it.

How To Learn This Skill

How does one make AC more robust? The answer is backlog refinement and practice.

Backlog refinement is the team venue where good stories turn into great ones. If you find iffy tickets getting into development, or further, you need a refinement practice.

You can also apply personal practice. Writing AC for a while across projects, you’ll start to see what kind of words leave space for misunderstanding, and develop tools to make on-the-spot corrections.

Conclusion: More Detail, AC That Works, Better Software

Including more detail in your AC almost always helps. Sweat the details when writing and refining tickets, where misunderstandings are cheap.

  1. This happens, even in the NBA, and is called an “own basket.” ↩︎

  2. This question demonstrates the Continuum Fallacy: https://rationalwiki.org/wiki/Continuum_fallacy ↩︎