Should user story scenarios (acceptance criteria) be used to describe the elements of UI?
More to the point, should the stories describe what the target UI looks like?
In this post, I’ll try to answer “Why UI has no place in user story acceptance criteria”. This naturally leads to the question “How best to handle UI requirements”.
Why UI has no place in user story acceptance criteria
Consider this, you sit in a co-located, cross-functional Agile team. You have UX/UI people, the developers, testers, and product all within the earshot. You’re one of the lucky ones!
The UX and Product people have spent time in advance thinking through the customer journey including screens and what the user experience will look (and feel) like. And they have built (sharp intake of breath), clickable wireframes!
Wow, looks like as a BA, you are in a pretty good spot. Suppose you pick up a story that has some UI elements to it. Lets pick the usual suspect, the login story.
The story goes something like, As a <some kind of user> I want to be able to log into the system So that I can use it. The UX people have come up with the following screen.
You have workshopped the hell out of various scenarios and you are now ready to capture the requirements in the form of scenarios for the story (in the BDD style of course).
So, should you describe, in intricate details, the different elements of the UI? Do you write something like…
Given I have a link to the system
When I click the link
Then the login page will be displayed
And it will have a text box for username
And a text box for password
And a function to Submit
And a function to reset password
When it comes to writing unambiguous requirements, translating pictures into words goes against all sense. It can give birth to too much confusion and misunderstanding. While we can list many different problems in the above scenario, lets just focus on UI in this post.
Keep your acceptance criteria independent of the solution
If one were to write the requirements for a login function like the example above, that would make the acceptance criteria too closely tied to solution. What if we could allow users to login without having to provide a username and a password?
What if we wanted different labels for the buttons or the text fields? We shouldn’t have to change the specification for small changes in the UI requirements as the intent behind the system behaviour doesn’t change. Moreover, the above style makes the specifications non-negotiable (as in the INVEST model).
Let’s rewrite the above example without involving the UI too much. Given that there is more than one avenue that the user can take while logging in, handling all that within a single scenario would make it complex. So let’s first specify what scenarios should cover everything that is important to cover in a login story:
- User successfully logs in
- User authentication failed
- User has forgotten their login details:
Scenario: User successfully logs in
Given a logged out user has been prompted to login
And the user has provided their login details
When they are successfully authenticated
Then they will see their logged in homepage
*P.S: I’m making up business rules as I go for convenience, although in a real life situation, where the user ends up after successful login may be driven by business rules.
Scenario Outline: User authentication failed
Given the user has provided their login details
When their authentication fails due to <reason>
Then they will see an error message
And they will be able to log in again
Examples:
| reason |
| incorrect username and password combination |
| user account is disabled |
Scenario Outline: User has forgotten their login details
Given the user has forgotten their <login detail>
When they request to retrieve their login detail
Then the system will send an email reminding them of their login details
Examples:
| login detail |
| username |
| password |
The above three scenarios capture the basic requirements associated with a standard login feature without being tied too closely to the UI or the solution design.
At this point, it would be useful to answer the question what role do user stories and specifications play in BDD. Where do they fit in the bigger scheme of things when it comes to defining requirements for a project. What is the purpose of writing user story acceptance criteria using, for example, the Given/When/Then format?
User stories and their associated specifications describe the behaviour of the system when a user (human or otherwise) interacts with it. When I include details of what the UI should look like in the acceptance criteria, I’m taking the focus away from what the specification should really be capturing; behaviour of the system.
One could argue that we can have separate scenarios covering the system behaviour and the UI, but that would just be muddying the waters. Remember, a useful specification is a clear, easy to read specification; adding unnecessary details would only make the specification long and hard to read.
UI requirements are more than just building text boxes and buttons
So what’s wrong with including UI details in user story scenarios? Describing UI in scenarios would be like saying “a word is worth a thousand pictures”, which, obviously, is quite counter-intuitive.
When you describe UI in user stories, you’ll probably use phrases like “there is a button”, but there is more to building a UI than just knowing that a button is to be built.
Assuming that we have established beyond doubt that a button does need to be built, there are other factors that need to be considered.
Factors like, where on the screen should the button be placed. What style button is it? What color schemes are we following? All these things are pretty important to most companies that operate websites because these factors are driven by the company’s corporate colours, accessibility, and the quest for a good user experience. To capture these details in words is futile while an actual picture will do a much better job.
UI details make the specification confusing.
Let’s explore the last point a bit further. Lets say that there is a requirement to make the login screen yellow.
You could write something like;
Given …..
When ….
Then the colour of the screen is yellow
Then you may also define what shade of yellow should it be. Is it the same shade of yellow throughout? Or is there a pattern that needs to be built? How does one describe these details in a specification? Even if we are able to, how do we keep it simple? And most importantly, how does it help us in understanding the intent of a feature?
Some common arguments against including UI in acceptance criteria
I have seen teams push back on the idea of not including the UI details in the acceptance criteria. I have listed some of the objections below:
1. This is how we define requirements
You may hear this if you’re joining an already established team. If someone’s idea of requirements is to put a couple of textboxes and a button on a screen, then they have got it all wrong.
When writing acceptance criteria for the login example, we must think about, as Dan North puts it, the what (the problem domain) and the how (the solution domain) of a login feature. The what here is ‘giving access to a user’, and the how may be ‘through the use of a username-password combination’. The what is essentially a business problem that needs to be solved, this problem typically will not change. The how, however, can change depending on the preferred solution. For example, we may choose a solution that involves a user entering a username and password, or we may use the services of a third-party authentication service, or a completely novel solution that doesn’t involve any of this. The point is, if we describe a username and password textbox in the acceptance criteria, then we are tying it too closely to the solution. We are also making the acceptance easily breakable with future changes (i.e. adoption of a different authentication method).
2. How will people who come later know what we built?
Reading documents is hard, and inefficient. If we want to show what we built for the purpose of training or showcasing progress, it is much easier to see the already built and working functionality in a production (or testing) environment. You have the advantage of playing around to learn more about the feature. For most people that would be enough to get familiar with it. For times when you need to know more about business rules working behind the scenes, there are always feature specifications.
3. How will the developers know what to build?
This is my favourite. As I have demonstrated in previous examples, writing down the details of UI doesn’t help, it only causes confusion. When UXers design screens, they take into account not only what ‘buttons’ should there be, but also, where is the best place to put them on the screen, their size, possibly colour and other factors.
Lets say you start elaborating the login story and it involves building a UI that will allow users to enter their authentication details and gain access to secure pages. Before you call the story ready for a developer to pick up, attach a printout of wireframes or designs that show the login screen in various states.
You can have a different picture that shows what the screen looks like the user has not entered anything, or when the user encounters an issue like incorrect login details and an error message needs to be displayed. If you are in a co-located team then you can use the wireframes during story kickoffs.
If you are in a distributed team where the developers and testers are in a different physical location, you can provide the wireframes and designs through a story management system like JIRA. Even a mock-up built in MS Paint, or a tool like Balsamiq, or a hand drawn picture on the back of a napkin will do a better job than UI features described in words.
A picture will be clear and unambiguous, and has better chance of prompting questions from devs or testers, which is a good outcome. After all as they say, “A picture is worth a thousand words”.
How best to handle UI requirements
UI is best described by, well, UI. When discussing how a screen might look like, it is always easier (and recommended) to draw a picture on a whiteboard or a piece of paper to show your understanding (or ideas). One of the key reasons to adopt BDD is to put the focus back on the behaviour of the system we are trying to build. Keeping behaviour in focus ensures that we keep the business problem that we are trying to fix in mind.
If you are at the stage where you are writing BDD scenarios, we can safely assume that the requirements are pretty well understood. You may even have access to clickable (or static) wireframes. Use your BDD scenarios to describe behaviour of the system and the business requirements.
During your story review, or kickoff (or both) bring out the wireframes/designs and let everyone admire their beauty. There will be questions (something surely is wrong if there aren’t any), record those conversations on the story card (or on the picture itself and attach to the story card ). That way you know what was discussed and if there were any changes required.
In conclusion, the most sacred tenets behind BDD are communication and collaboration, and the best way to describe UI requirements is through visual communication.
