What is your favourite part of an IT project?
Mine has always been writing user stories. It is when all the ideas take shape and begin their journey to a shiny new product. I know that not everybody feels the same way. I understand why, especially when it comes to writing User Stories for back-end systems, for example, APIs, as these can be particularly challenging.
In this blog, I want to share my tips and tricks on writing Agile user stories for API-led integration projects.
Follow my tips to write User Stories that bring value to the whole team!
The Agile user story in APIs context: the challenges.
Let us start from the beginning. Why create user stories? Because a well-crafted user story is a powerful tool. It helps the team visualise and understand how the features they are designing will benefit the stakeholders of the product or service. Each user story must capture the benefits that a piece of work or a sprint will bring to their product and help manage the product backlog. Well written User Stories that express the end value also facilitate the decision-making process.
User stories help manage product backlogWhat makes crafting a user story for APIs so challenging?
- The functionality is likely to benefit more than one persona, and joining them all in a single statement is not easy.
- It’s harder to identify the ultimate “customer” of the APIs we need to build because we need to see past the developers who are the “hands-on users”
- The need for user stories is often overlooked as the technical aspect is so crucial that all the energy is focused on developing the requirements.
What are the aspects of a well-crafted user story?
I follow the 3C model described by Ron Jeffries in 2001. The 3C model is the grouping of three essential terms to describe the User Stories: “card”, “conversation” and “confirmation”.
Based on the model, a good quality user story should be:
- as short as a card,
- result of multiple conversations within the extensive team,
- have a formal agreement on the validation rules (confirmation).
I find that by following the 3C approach during the discovery phase of my project, I can build the basis for high-quality user stories.
When crafting my user stories, I’m thinking about both the development and business teams. On the one hand, the development team wants to understand the context and the technical details behind a user story. They need to evaluate the complexity and feasibility of the requirements.
The business team, on the other hand, will look at the value that is created by the project. I feel that a well-written user story brings the business and technical worlds together and improves the collaboration between the customer and the tech teams.
Now let’s move on to the practicalities of writing an excellent user story!
How to write a great user story: Who
The Agile user story template is a simple sentence structured as follows:
“As a [persona], I want [to do something], so that [something else happens].”
This template gives us all the elements to write User Stories for integration projects and is also a great base for any other project you may have.
The first thing to do is to pinpoint our “persona”. In general, it is always a good idea, during the discovery phase, to detail the “Persona”, a character that identifies the end-user of the product we want to implement.
To find our “Persona”, we have to consider:
- Who is the end-user?
- Whom are we building for?
- Who will benefit from this story?
In a nutshell, what we are looking for is detailing an actual persona that will benefit from the development that the story delivers.
For example, our customer EzPC, a company that sells online PC components, wants us to build a set of APIs to integrate their website and the products database.
Who is the actual persona that will benefit from the development that the story delivers?One of the User Stories in our product backlog has to cover the build of an API to show the available products on the website.
In this scenario, the temptation is to write the user story as follows:
“As an API, I need to read the products database so that the spare parts available appear on the website”.
Although this sentence describes what the API should do, it does not give us the big picture. We do not know what is the value that this development is bringing to the solution and to the end-user. The lack of context makes it difficult for the team to understand why this user story is important for the project.
Let us step back and think about who our “Persona” can be:
- Mario online buyer,
- Ruth EzPC products database manager.
Now we can rethink our requirement and the impact that it has on our “Personas”; our user story can then be:
“As Mario, I want to browse the online products list page so that I know what is available”.
Or:
“As Ruth, I want to update the products database so that the products available appear on the website”.
The sentences above give us more context and tell us the value that this piece of the project wants to deliver. By associating the “Persona” to the product functionality, we immediately have a broad picture of what the goal is.
In some circumstances, it is possible to have a “System Persona”. In these cases, in the user story, we will name the system which is going to benefit from it or the one which is going to perform the required action. This exception may come in handy when we want to narrow down a bigger user story in projects where multiple systems are involved.
How to write a great user story: What
The second element we define when writing an Agile user story is the action that our “Persona” needs/wants to complete.
This element appears in the second part of the Agile user story template:
“As a [persona], I want [to do something], so that [something else happens].”
At this point, we want to describe our “Persona” intent, what they are trying to achieve.
In integration projects, this activity is probably easier than identifying the “Persona” itself.
Knowing that the main HTTP verbs when building APIs are:
- POST,
- GET,
- PUT,
- PATCH,
- DELETE.
We can easily translate these verbs into a less technical language:
- Create,
- Read,
- Update/Replace,
- Update/Modify,
- Delete.
So, going back to our EzPC project, if the requirement is to show on the website the new products added in the database, our user story is not:
“As an API, I have to POST new products on the website so that I complete my job”.
But:
“As Ruth, I need to create new products on the database so that they appear on the website”.
Tip: As this last user story example shows, when we write user story in API context it is important to specify both the source system and the target system. By doing so, we will give the development team an indication of the data flow.
How to write a great user story: End Goal
Finally, the last element in the Agile user story template asks us to specify the end goal.
“As a [persona], I want [to do something], so that [something else happens].”
This part of the user story allows us to detail what we are trying to achieve, to express what is the value we want to deliver to the stakeholders.
To complete this last piece of the Agile user story template, we could think about:
- Why should this action be completed?
- What is the overall benefit we are trying to achieve?
- What is the main problem to be solved?
Looking back at the examples we wrote so far:
“As an API, I need to post new products on the website so that I complete my job”.
Again, this example does not give us a good enough excuse to proceed with the implementation of this user story: “So that I can complete my job” it is not a very good reason to push our customer and the team to implement this story.
Don't skip the end goal part of the user story!Contrarily, the example below gives us more details on what we are trying to achieve:
“As Mario, I want to see all the new products on the website so that I can shop online”.
Associating a meaningful value to the User Stories helps both the business and development teams better understand the significance of the work we need to undertake.
I hope that I have convinced you to give the Agile user story for integration or a back-end project a try! They may seem more complicated and troublesome to write, but the effort pays off in our experience! User stories allow both my team and my stakeholders to maintain the focus on my business end goals and the product value I want to deliver.
Follow the 3C model and my tips and share your experiences with user stories; I will be happy to support you with further advice! Do you have any other tips on great user stories, please share those in the comments!
