I had a manager once who would constantly harp on both the product team for not writing stories with good acceptance criteria and on the engineering team for accepting these “poorly written” stories. He would claim that his engineering team was the engine, and it would only perform as good as the fuel you gave it.
If you’re familiar with Agile, then you’ve probably had the general story format of “As a [USER] I should be able to [DO SOMETHING] so that I can [ACCOMPLISH SOMETHING].” beaten in to you. It’s a great concept, and as a Scrum Master, I can say that it does work. Of course, you don’t have to take my word for it (even though I hope you will). Mike Cohn of Mountain Goat Software, one of the authorities on Agile and Scrum discusses the advantages of the As a User, I want User Story Template.
Here’s the one problem I have with using that format: Engineers get their hands on it. They bastardize it. They take it to be gospel. They use it to not have to think.
I’ve had engineers who would write system level stories with things like “As a System, the System should have Logging, so that the Developer has something to look at with things go wrong.” Gee, that’s nice. What are you trying to log? How will you access the logs? (which should really be another story quite honestly…) What sort of things do you mean by “go wrong?” And of course, my favorite bit, “As a System, the System should…” Is the web server actually sentient and have a concept of self? (Try and bend the process and I’ll pick anything and everything apart…)
Then there’s the individuals who just don’t want to follow the format. “Why?” they whine. “What’s wrong with just attaching a picture of the white board from the meeting we were all just in to the story? The devs who will build it are in there.” You should definitely add the picture. It’s an artifact to the process. But don’t rely on it! Weeks could pass before the team gets to that particular story. A crucial team member could get hit by a bus or win the lottery. You need context to the story.
I’ve seen issues even following the format to the letter. This arises from the statement being too vague and the product owner expecting more than they wrote. The engineers take those vague statements as gospel, and then hide behind it as the story doesn’t pass, or ends up having three more stories written to clarify the original work. They use it as a crutch to not have to think about more than what was written and potentially not deliver greater value. I once saw a story rejected because the statement was “As a User, I want to be able to log in and see what I have permission to see.” A little vague, but tolerable. The story was failed because of a different issue; the product owner didn’t like the error messages displayed if it was a failed login attempt. Funny, I didn’t see anything in the sentence regarding failed login attempts… You know what would have alleviated this issue? Acceptance Criteria.
By explicitly stating after the “As a User…” statement what the expected results would be this could have been avoided. Acceptance Criteria for the above log in story could be as follows:
- The user will be able to enter their user ID (email) and password and select the button labelled “Login” to log in to the system.
- If the user enters an incorrect ID and password combination they will be presented with the login screen and an error message above the fields stating “You have entered an invalid ID or password.”
- When the use successfully logs in they should see content appropriate to their User Roles:
- Standard users will see their dashboard with content they have subscribed to defaulting to the last 30 days ordered from newest to oldest
- Staff will see the internal dashboard
- Admins will see the internal dashboard augmented with extra tabs for user account management and subscription payment management
So how do you write good acceptance criteria?
Think of acceptance criteria as a helping guide for how you or someone else would test this work. No amount of detail should be spared on your road map of how to verify the story. In some cases it could be as detailed as an AAA TripTik (If you ever had a paper one made for you, you’ll know what I mean). It often helps to draw out a flow chart or build out a spreadsheet of desired actions and possible outcomes. For the login example, the spreadsheet might look something like this:
Login Acceptance Criteria Example
| Page | URL | Action | Expected Result | Data Needed |
|---|---|---|---|---|
| Login Page | /login | Login as a standard user | Standard users will see their dashboard with content they have subscribed to defaulting to the last 30 days ordered from newest to oldest | User: standard@sample.com Password: password |
| Login Page | /login | Login in as a staff user | Staff will see the internal dashboard | User: staff@sample.com Password: password |
| Login Page | /login | Login as a system admin | Admins will see the internal dashboard augmented with extra tabs for user account management and subscription payment management | User: admin@sample.com Password: password |
| Login Page | /login | Attempt to log in as an invalid user | User is redirected to the login screen and is given an error message above the fields stating “You have entered an invalid ID or password.” | User: baduser@sample.com Password: badpassword |
While this will often fall to a designated QA individual or team, not every organization is set up to have a dedicated QA group. Regardless of if you have QA available to you or not, be sure to write the acceptance criteria with enough detail that anyone in your organization could follow the steps. It will help with testing, and it will help with development. If you do have QA available, engage them to help you write Acceptance Criteria that will help all of you. They’ll have plenty of tips to give.
So back to the fuel… You can give your engineers basic requirements, or you can give requirements and acceptance criteria. One will act like 87 octane in a Corvette; you’ll get there, but there will probably be some sputtering and a few issues down the road. The other is going to be like putting in 93 octane in that same Corvette; it’s going to purr and give you much better performance in the end.