This is the first part of a multi-article series to elaborate on the user story structure, and what I have learned over time about how to write a user story for Agile software projects.
Foremost, despite referencing the word story, let’s remember that user stories are product documentation for stakeholders in the organization (including developers). They are not just notes for the product manager/owner to refer and update over time. Each user story is a piece of the complete requirements manual for the software product, and should be treated with some level of formality. After implementation, stories should live on and remain as reference to be incremented upon.
In the software development universe, user story variations abound. But since I’m writing this article and the universe isn’t, I’ll stick to what we at Planorama incorporate into ours:
- Acceptance Criteria
- BDD Scenarios
In this installment, I’ll start with the narrative. Here is the structure we use, and I’m sure it’s familiar:
As a _______________
I want to ___________
So that I can __________
You can see this is written with brackets above since it’s an optional clause in the narrative. The purpose here is to setup any preconditions for this user story to be valid.
Preconditions? If you think this is beginning to sound like coding instead of writing in plain English, don’t worry – let me explain:
Let’s talk about a user of any given application: For what that user can do in the application, is every feature available all the time? If the application can have a state in which a feature is only available (or, inversely, a state in which the feature is NOT available), then the GIVEN clause is where you specify that. For example:
Given the application has disabled user logins and sessions
As a system administrator,
I want to add a new client…
This example implies that adding a new client cannot be performed while other users are logged in, and therefore the feature isn’t available all the time: it depends upon a state of the application.
GIVEN is informing the reader about a special application STATE, not about what the user is doing. We SHOULD NOT use it when:
- Referring to a location in the application or UX (e.g. Given the user is in the admin panel…)
- Referring to a step in a simple workflow (e.g. Given the user just entered his/her user name…)
As a …
Now, finally the line we’re all used to: stating the WHO. Who is using this feature? And for the love of God, please don’t write, “user”.
How many WHOs are we talking about?
First, let’s decide if it’s one WHO, or multiple WHO’s. Are there multiple types of users who will use this feature? If there are multiple, here’s the follow-up question: Do they each have the same experience with this feature?
For instance, if the feature can be used by both a regular user and a system administrator, are their experiences identical? If so, then keep as a single user story. However, if not, you may want to create a separate user story for each. Why? Because the user story will begin to bifurcate and look like conditional code. Later when the UX is included, you will have to make annotations such as, “If it’s an admin, this shows up, but if not, this other thing shows up.” Now we are making the software developer interpret that complexity. Unless the differences are trivial, then consider splitting the user story into multiple stories, each with their own WHO.
As a [persona], or As a [role]?
Second, decide what the WHO(s) refer to. Are you referring to persona(s) garnered from user research, or as user roles in the product? I advocate for both if you have them available, but at least the user role. For example:
As a student (adult learner)
In this case, the student is the role in the system, and adult learner is the persona – a particular type of student user research has identified. However, specifying the user role (student) at a minimum is key because the rest of the user story needs to reference who is using the feature. In addition, specifying the user role allows developers reading the user story to directly correlate to the software implementation.
I want to …
With the WHO cleared up, now we’re talking about user’s intention – what the user wants to accomplish. It’s the feature’s action.
Often I’ve found it helpful to consider actions upon information (or things). Actions are verbs, like CREATE, VIEW, EDIT, DELETE, REORDER, COPY, MOVE, etc. These words will especially trigger developers (in a good way) to consider these as possible services / API endpoints that support these actions (think, CRUD). Then, information / things are the major data concepts that are naturally part of the UX.
For instance, if we are designing an LMS (Learning Management System), the major types of things that may be included are programs, courses, classes, students, instructors, etc. Each one of these will need to have some actions performed upon it, such as creating, viewing, editing, removing, setting an order, setting prerequisites, and more. When we think in this way, writing this section becomes more obvious, and even illuminates what other user stories may be required.
So that I can …
The final line of the narrative, this is where the product manager’s empathy for the user illuminates in the user story. What is the motivation behind the user’s actions? What is the value or benefit to the user by using this feature? Ultimately what is the user trying to accomplish?
While you may be tempted to pay little regard to this final line of the user story narrative, it actually provides wonderful context for the entire story. In addition, this can help others on the team, outside of the original story author, brainstorm ideas for how to design and implement this feature.
As a system admin
I want to create a new client
So that I can …. have a new client?
I know – it looks stupid. We’ve all been there, brainstorming what other motivation could there be? So let’s expand this example a bit:
So that I can sign-up a client quickly while on the phone talking to them.
So that I can create the client from the list of clients I received from sales.
Now we’re empathizing with the system admin’s situation: Does she need to create a new client fast over the phone, or while on the go, or one-by-one, or with another 30 clients to add right afterwards? Ahh, suddenly the context leads us to think about other solutions entirely. Maybe we should consider a method to import multiple client’s information quickly from a file. Maybe we need a mobile method to do this. Maybe the UX has to be super straight forward so creating the client while talking on the phone with them is drop-dead easy. Maybe creation of the client happens in parts, so the essentials are captured first, and then the admin can follow-up later with non-essential information.
See? The “so that I can” section may actually prompt entirely new solutions, and new user stories.
Stay tuned for the next installment of this article, focusing on user story acceptance criteria.