Requirements that impress
- Richard
- Feb 14, 2020
- 5 min read
As promised, this blog I'll explain how to write requirements that leave a lasting impression. I'm not trying to tell you how to write a user story, just the requirements for a project.
So you're starting a new project, you're going to need a requirements document that is clear to the customer and the developers on what is in scope. You're taught to go for user stories and you've done a good job at it. You've written down the stories that the developers can work on and the customer agreed upon and you leave the project to run it's course. A month or so later you get called in a meeting, apparently the customer is upset, but what do you have to do with it? Hesitantly you enter the meeting room filled with frustrated faces and you sit down still wondering what went wrong. And here it comes, the user stories were interpreted differently by the developers and the customer. How could this have happened? You followed every rule laid before you.
"The user wants to log in with SSO so they don't have to remember additional passwords"
Sounds like a solid user story right? Sure you could've gone more specific in saying it's SSO with an Active Directory, but that might've just confused the customer, and you've already talked this through with the developers. Then why did this become a problem?
Let me tell you why this user story is a problem:
Does the customer want to be signed in automatically every time he visits the site or does he want a log in button?
Does the customer want to include provisioning?
Does the customer want to set up automatic certificate renewal?
Does the customer want to be able to log in with different methods as well?
I could go on, but I guess my point is clear. Sure you could've written more user stories to tackle all these questions, but would that really have helped? My suggestion is one not often heard in this community: throw user stories out of the window. I am yet to see a user story that doesn't raise questions. Sure you can 'solve' this by writing all the details in the acceptance criteria, but unfortunately that's not always possible. Sometimes you have all these details that can't be catched in a user story, or you have a user story that's the same as the Feature you're going to write the details for. Not going to work, I've struggled with this in the past myself. So how do I do it now?
Throw user stories out of the window.
For all the newcomers, let's start at the beginning. There's Epics, Features and User stories. Epics are huge, Features are a bit smaller and user stories should be big enough to deliver content but small enough to be delivered within a sprint. That's the basics of agile. So when I start a project, I dub the project as an Epic. A project consists of different milestones, dubbed by me as the Features. Then there's the user stories that I don't use, instead I write scenario's. So let's get back to the example we've used before.
Starting with the project. The customer wants to hire a software company who is able to create a website where the stores can order products from their warehouse. This will be the epic. Sometimes projects are so big you need multiple epics, but I'm going to keep the example easy.
Epic: The customer (a warehouse) wants to have a portal where users (the stores) can log in to order their products.
During a workshop with the customer you discover what kind of Features the customer wants, SSO, account details, repeat orders something like a shopping cart. Oh! And the ability to highlight new products.
You write it all down, and add some common sense Features:
Feature: The customer wants to have a login screen
Feature: The customer wants the user to be able to login through SSO
Feature: The customer wants the user to be able to store personal details
Feature: The customer wants the user to be able to see their current order
Feature: The customer wants the user to be able to add items to their current order
Feature: The customer wants the user to be able to edit the amounts in their current order
Feature: The customer wants the user to be able to delete items in their current order
Feature: The customer wants the user to be able to see previous orders
Feature: The customer wants the user to be able to repeat previous orders
Feature: The customer wants to be able to highlight new products
Now it's time for details, do you want to get the login screen as soon as you go to the site, or do you want to be able to navigate through products before logging in? Straight to login, okay. Then do you want to give different login options? Or just a seamless transition through SSO? Multiple options, got it. What options? Just username/password and SSO, check, this will add a new Feature. And this way you ask questions until you've got the entire picture in your head. You promise to deliver the requirements somewhere next week, because you want to run them past development as well to see if there will be any technical difficulties.
The next day, you sit down at your desk and grab your notes. You start making some wireframes for everything they've asked. This helps you visualise everything they want and need. This also helps you explain it to the developers and the customer later.
Good job on that wireframe, almost forgot about the checkbox to remember the user. Got to add it to the requirements.
So, we already had some Features written down, and we need to add some new ones:
Feature: The customer wants to be able to login with credentials
Feature: The customer wants the user to be able to register
Feature: The customer wants the user to be able to reset their password
Feature: The customer wants to be able to suspend accounts of former employees
Ok, time for the details on the Feature:The customer wants to have a login screen.
You think of all the possible Scenario's, name them and write them down:
And to give an example of a form:
This way, there can never be discussion about interpretation. You write down all the possible scenario's, even the most obvious ones. This helps later on, when you put this on the backlog. You immediately have your test cases done and there will be no risk forgetting details between signing off on the project and actually starting work on it. So it takes a lot of time and effort pre-project, but you win double the time back during the project. And I can say from experience, you'll get pretty quick at writing these scenario's.
So when you're all done your requirement document will look something like this:
If you manage to follow me in this way of writing requirements I can promise you the customer, the developers, the product owner, the testers, basically everybody involved will love you for it.
Comments