How Visual Acceptance Criteria Speeds Development

September 3, 2020
Aug 11, 2022
Read time: 
How Visual Acceptance Criteria Speeds Development

What Are “Acceptance Criteria”?

In agile development, acceptance criteria lists the requirements that must be met for a development story to move to the next phase in the development process on its way to being considered “done” or complete.

If a project manager writes a user story, then the assignee that works the story must complete all the acceptance criteria. When the work is reviewed, it’s checked against this list of requirements. As long as all the acceptance criteria are met in-full, the work must then be approved. Any changes must be a new request that either become an enhancement story, a new task, or a bug fix. Do not confuse an enhancement story or task with a bug fix. This has serious implications for the developers -- the reasons for which I’m not going to dive into in this particular article. In this way, the writing of good acceptance criteria is vital to getting work done, keeping the development process moving forward, and avoiding any backtracking.

The writing of good acceptance criteria is vital to getting work done, keeping the development process moving forward, and avoiding any backtracking.

Why Should I Care About Acceptance Criteria?

Comprehensive, clear, and concise acceptance criteria (ACs) are paramount to successful and efficient development.  In addition to unnecessarily complicating the story, this can lead to poor rapport between stakeholder and developer(s). I’ve witnessed how poor, vague, or ever-changing acceptance criteria slow engineering to a creep. Vague acceptance criteria cause grooming to take longer, leave elements up for interpretation, or miss key details.

Missing or incorrect details lead the developer to ask certain questions after the story is already being worked. So now we must load the train while it’s already moving. The developer has to stop working the story to re-groom the story; this is called Just in time grooming. My resulting opinion from my first introduction to it is that it’s a foreboding of acquiescence to poor adoption of agile strategies and tactics. As a result, the agile team now has inserted a pathway for stakeholders to inject new requests at whim; thus you are no longer agile. Instead, your team is now using agile jargon and tools to conduct waterfall development.

How Long or Detailed Should Acceptance Criteria Be?

While we might not want to admit it, lengthy acceptance criteria may not get read fully. “You don’t need to write War and Peace” is great advice that my Agile Lead often doled out to the team. Many developers volunteered that they relied heavily on the abstract or summary before getting started working a development story. So, concise language is key to successful absorption of acceptance criteria. 

Keep it to the minimum that is necessary to communicate the idea fully. If that can be done with a single paragraph summary and a bullet point list with the inclusion of the visual, then that’s the maximum text needed to fill out your ACs. Evaluate your success based on how often someone needs to ask you a question about your ACs. Once you feel like you could write your user story and go on vacation without problem, you’ve mastered the art of writing acceptance criteria.


How Do You Visualize Acceptance Criteria?

Try to think of everything in terms of a flow. In that way, you must tell the story of the end user. That’s what we all care about.

Interactive Prototypes

As a User Experience professional who primarily works with the user interface, I generally prefer to communicate my acceptance criteria with an interactive prototype. I prefer Axure, but tools like JustInMind or Balsamiq also fit the bill. The interactivity allows the developer to walk through the flow step-by-step with a clear illustration of what will be seen on the screen at each point in the experience. In the end, I write very little in the story, because the prototype is the meat of the acceptance criteria. I will see the developer clicking through the interactive prototype and reading the annotations. This is the type of in-context knowledge share that software engineers actually get excited about and will thank you for.

Because an interactive prototype presents an entire flow, you may sit down with your developer and have them break the flow into chunks of tasks. Those become stories that are dependent upon each other. This is a collaborative way to make sure your stories are developer friendly.

The popular thing nowadays is to use Sketch or predominantly visual design tools to create flat visualizations to illustrate a static moment in the users’ experience. This gives the developers a lot of key visual information -- just as the prototype will -- but lacks the interactivity that allows the developer to know exactly when, where, why, and how user interface (UI) components appear and disappear from the screen when the end user is trying to complete a task. The use of tools like Sketch are better than nothing, but using such tools lead stakeholders to expect pixel perfect mockups. Creating pixel-perfect mockups takes a lot of time and is not necessary to communicate to developers. 

There is an appropriate fidelity level for every type of human-centered design. High fidelity is almost never the most appropriate. I find that when given high-fidelity mockups, stakeholders will waste time scrutinizing the styling that is globally dictated by the design system in play. As a result, the human-centered designer has to spend time explaining design details that will be addressed by the design system, rather than focus on the users’ experience of moving through the steps to achieve the desired outcome. 

Key Considerations for Using Prototyping Tools to Visualize Acceptance Criteria 

Note that regardless of which prototyping or design tool you use, the assignee taking on your user story needs to know when to click what and what is relevant to the story. If your team is well integrated with HCD, then much of the knowledge share will happen organically through co-design, collaboration, and findings read-outs from UX research. When that ideal is not achievable, the human-centered designer should share the version of the interactive prototype that highlights all the clickable hotspots; this is provided by most of these tools.

For example, InVision has an excellent feature called “Tour Points” where you can provide asynchronous walk throughs of your prototype. I highly encourage you to take a tour of Tour Points.

Making It Easy for Your Development Team

Don’t forget that all of these tools have an existing or beta Inspect Mode, which takes a hefty load of guesswork out of recreating your design -- especially if the designer is required to create high fidelity or pixel perfect screens. Inspect mode is like the developer mode on your browser in that it allows the developer to click on elements in your mockup to view the measurements, details and bit of code that they need to make the application look identical to the mock.

While I’m advocating for making your acceptance criteria more visual or as visual as possible, I don’t believe that your criteria should be purely visual. You should definitely include a light-weight checklist of what the developer will be evaluated on in the ACs. 

This is one of the not so small ways that we “empathy workers” improve the developer experience.

How to Visualize When There’s No Interface

Visual acceptance criteria isn’t limited to user interfaces. Regardless of whether you have a front end, ACs can be visualized using a diagram or annotated screen captures. While visualizing a user story, the development ask is a key ingredient to efficient, comprehensive communication of any individual acceptance criterion. The text-based content in your ACs must provide the key elements within the visualization -- like a checklist of things to look at. This will allow the developers to “test the completeness of the story and support automation testing down the road,” says John Royle, an Agile Engineering Lead.

Flow Diagrams

Consider the humble flow diagram that may break down how a backend system can and should work. Rather than writing lines upon lines of acceptance criteria expounding in excruciating detail how the service call to the API will play out, instead chunk the information into shapes and lines that another person can follow. “The flow diagram is the acceptance criteria” is a phrase that has lifted the corners of mouths in an upward motion. When I have done so, it saved hours of heads-down writing time for a product leader and told the full story of what needed to happen in an extremely confusing and complicated process.


Tools for Flow Diagrams

When creating flow charts, I prefer Flowmapp. It is fairly inexpensive and allows multiple people to work remotely on the same flow document. That flow document can be constructed with relationships between the sitemap and user personas. It has digital sharing capabilities and integrations with tools like Slack. It also allows the designer to inject their screens into the flow diagrams, enriching the understanding all the more. This is invaluable. I recently created a flow diagram for an extremely robust login flow that had more complexity than you could possibly imagine. The export to PDF and/or SVG is flawed but is the only option if your stakeholder doesn’t have a paid account.

Other tools like Miro, Mural, and Google Draw have the capabilities necessary to create flow diagrams. If you already have access to an application that allows you to place text inside of boxes and connect them with lines, you may not need to invest even in a relatively cheap tool to accomplish what I’m suggesting.

More Efficient Development

Remember that everyone involved in the development process is a person, and people consume visual information faster than written information. You know the saying “a picture is worth a thousand words”; well, that applies to acceptance criteria too. 

If you want to communicate your vision and desired outcomes effectively with few mistakes or missed opportunities, then you should create an example that people can see and interact with. 

Visualizing acceptance criteria isn’t difficult, expensive, or time consuming. You will save everyone hours in the work day at an exponential rate. Time is better spent digesting the criteria, asking questions to fill in the gaps in the users’ story, correcting mistakes, and grooming the story. In short:

Make something visual. Make someone’s life better.