Writing Technical Stories

Recently I gave a talk about writing technical stories and ways I have found to slice user stories thinner at Product Camp Toronto. I thought it’d be good to share some ideas from that talk here as well.

I work as product manager for epost which is one of the biggest online document delivery and management systems within Canada. epost allows users to view, pay and manage bills online and roughly one in ten Canadian use it to view their pay stubs, utility bills and tax statements among others. Right now I am in charge of leading a scrum team to redesign epost to improve web and mobile user experience. I am also responsible to revamp epost API service calls and to integrate them with Canada Post, banks and mobile apps.

My team is one of the first teams working Agile within Canada Post, so we are all new to the concept of finishing user stories within a two week sprint. And after the first few sprints I realized that we were constantly behind schedule. Our flow for getting a story done looked something like the following:

user story flow

Creating API call and gateway call would take half sprint and front-end will work on the last leg of sprint to get it done. So when the story was ready for QA we were out of time and stories kept piling up to the next sprint!

I also realized during our sprint planning and release planning a bunch of tasks get discovered and brought up that are not identified earlier. By the time these tasks are done, we are already late with the sprint. It was clear to me that I needed to write smaller stories but how?

With a help of a my great Scrum Master Peter Moreira and User Story Mapping (I review the book in a future post) I came of with the following strategies.

Write Technical Stories (when necessary)

I decided since any given back-end service call will be consumed by multiple end-points it makes sense to slice a story further into an API-specific one and a front-end/UI one. API story is still valuable and independent (sort of) but it can be estimated and worked on by itself. This way I could prioritize the API story ahead of front-end story to provide much needed time for UI and QA to be done.

This was great however I didn’t know how to write user stories about API, web services and other technical stories that are not necessarily user facing. More importantly I was struggling to fit the story into “As a user I want to — so that I can —” template.

“As a front-end developer I need to supply mail list data so that it shows as a list view of mails” sure sounds weird!

I came across this excellent article that confirmed my belief not to fit the story into a template when it doesn’t fit. So for technical stories I clearly write Who the end-points consumers of the API call will be, What is expected acceptance criteria of each of the end-points are and what it the expected output of this API is and finally Why this API call is important to develop. I talk to developers to understand what does API generate, how it can be validated and make sure there is alignment on acceptance criteria prior to grooming session. From my point the story is usually done once I can see API call and the data generated in Swagger and all the security criteria is met.

So a user story that looked like this before:

—As a Chief Household Officer, I want to filter mail by service provider name so that I more easily find my mail

the API story will look like this:

—We need an API call used by Canada Post, native app and our bank partners to filter mail by a service provider so only mails by that provider shows up

Acceptance Criteria

  • Verify that the request get thru the service layers and receive a reply within 2 seconds
  • Verify that the request has necessary Oauth permission to be exposed externally
  • Verify that the request is generated in both XML and JSON formats
  • Verify that records are returned from oldest to newest

—Separate Success and Error Stories

Another trick I’ve found effective to write smaller stories is to focus one user story only on the happy-path, while writing other stories for when things went wrong, edge cases. For example for file creation user story write one story specifically about creating a file without any problem but write several more stories to cover the file name maximum character, acceptable  characters etc.

I would love to know if you have other ways to slice a story further. Please share them with me in the comments below!

Leave a Reply

Your email address will not be published. Required fields are marked *