Story Slicing: A Real Life Example

This is a real life example of how we split a large user story, sometimes called an epic, into manageable bits of less than two days. By doing so we can amplify learning, get feedback early and reduce risk.

This functionality will be part of a platform we built for a customer. With this platform consumers can order products from affiliate webshops through an app.

It consists of an app (iOS & Android), a management web portal, various databases and several back-end services accessible through an API.

This is an existing platform, so a lot of infrastructure is already there. It means we have to be careful not to break existing things.

Currently, the payment of an order is not done in the app. Affiliate webshops have to work out payment with the customer for themselves when an order comes in.

Understandably, for webshops this is a hurdle to join the platform. Also, consumers expect to be able to pay for their orders right away in the app and do not always want to pay on delivery. For these reasons enabling payment in the app has become the #1 feature on the backlog.

Our customer has done the legwork choosing a Payment Service Provider (PSP). We have worked with other PSPs before, but we haven't worked with this particular one. We find it hard to gauge how much work the whole story will be and what challenges we may encounter.

Spike

The first thing we do is define a technical spike to analyse the possibilities and restrictions of this specific PSP. We spent a day or so playing around with their API on a sandbox environment and reading their online documentation.

We are now fairly confident we can realize the features as asked for by our client and do so in a reasonable timeframe.

We have also learned that there are two major parts necessary to implement the whole payment story:

1. Allow webshops to register with the PSP as customers of our platform
2. Allow consumers to start payment of their order in the app

The order in which these two things have to be built is obvious. We can't let consumers pay in the app if we can't transfer the money to the webshops, so #1 has to be implemented first. Along the way we will probably learn things which will be useful when implementing in-app payment.

Register a Webshop as PSP Customer

To register webshops with the PSP we have to implement a tab in our website where an affiliate webshop can:

1. Start the registration process. This will open up a web page on the PSPs hosted environment.
2. See the status of registration, when started but not successfully finished. This might be "In Process" or "Failed". Each status has a specific explanatory text and icon
3. See their PSP customer reference number and bank account number, when registered
4. Click on a link to the Terms and Conditions
5. See a succinct help text
6. See a Success dialog when registration is completed successfully
7. Automatically and periodically refresh the screen when a payment is "In Process" to check for any updates (notification of registration is asynchronous and might take a few minutes to finish)
8. Let the webshop change their bank account number registered with the PSP

We decide to focus on #1 and #3, because those steps are necessary to register webshops as PSP customers. Seeing the results will allow us to verify whether registration has succeeded. The other parts of the story can be deferred until later.

The registration may return a number of results, such as Success, Failed, Cancelled, Success & Abort, Pending, etc. For the first story we decide to focus solely on dealing with the Success result.

So, in summary, we distill the first story to building a tab in our portal where an affiliate website can :

1. Start the registration process and open a web page in the PSPs hosted environment
2. See the resulting customer reference number as returned by the PSP and the bank account with which they registered

This is a so-called tracer bullet story. All components necessary for the completion of the larger story will be touched, but in the most marginal way possible. If there are any troubles connecting to the PSP, or if implementing the flow of a payment result proves to be difficult, or if there turns out be something we didn't think about we would rather find out sooner than later.

Tasks

The following components have to be built for this first story:
1) A table in the database that holds:
- Webshop Id
- Customer Reference number as returned by the PSP
- Bank Account number
- Payment Registration Status
2) An endpoint to retrieve the Payment Registration Status of a Webshop
3) An endpoint to Start Payment Registration
4) An endpoint to receive a Payment Registration Notification from the PSP
5) An endpoint to Get Payment Registration Info
6) A tab page that depending on the Payment Registration Status shows:
- A partial webview for starting a Payment Registration
- A partial webview for showing Payment Registration Info

We figure each of these tasks should take less than two days to complete. They are also atomic, meaning they can be built and deployed without interfering with the rest of the application, except for #6 which has to be behind a feature flag if we want to deploy to production without this feature enabled.

It makes sense to build the components in the order in which they are summarised, but it is not strictly necessary. Several of these components can be developed in parallel, although that does mean close communication between the individuals or pairs working on them to determine the interface between these components.

Aftermath

Building this story first allowed us to learn about the challenges and opportunities working with the API of this particular PSP.

A thing we discovered, for example, was we didn't actually need to store the Bank Account number and the Status with the Registration, but that we could retrieve them from the PSP with a simple call when needed.

We also learned that we wanted the pages on the hosted environment of the PSP to be in the same language as the app, a feature we hadn't thought of beforehand.

Another boon was that, while working on the story, we could ask some specific questions to the PSPs support desk, opening up a channel of communication with them. They informed us of some features that would be released shortly that could be useful to us, which we otherwise wouldn't have known about.

Summary

In this post a real life example was shown of how to split up a large user story (epic) to make it manageable, reduce risk and amplify learning.

First, we split up the user story by user type: webshops and consumers. Then we singled out a single "tracer bullet" flow to implement first, leaving the other flows for later.

For this first story slice, we left out user interactions, such as help texts and dialogs, that will be useful to have at some point, but that we do not need for now.

Finally, we chopped up the remaining functionality into technical tasks that are each less than two days work and can be developed separately and in parallel with each other.

A Review of Clean Architecture

Robert C. Martin's ("Uncle Bob") Clean Code was a real eye opener for me when I read it a few years ago. I learned many things from Clean Code and it made me a better programmer.

Recently I've become increasingly interested in software architecture. So when I heard Clean Architecture was coming out, I ordered it immediately.

As I was pouring over the Table Of Contents in preparation of this review I caught myself thinking: "Did I read all that in just a few days"?! That really is a testament to Uncle Bob's ability to make such a book a breeze to read. It is very accessible, sprinkled with personal anecdotes and a bit of humor.

Due to the nature of the subject it is somewhat less readily applicable to my everyday work than Clean Code is. Still, it is a very practicable book, a few more theoretical chapters not withstanding. Certainly, next time when starting a new project I will apply a Clean Architecture.

The book starts out by defining what architecture is and isn't. Martin makes the point that a good architecture should make it easy to change the code when requirements change.

What follows is a nice overview of the history of software engineering and how programming evolved, including a summary of the three programming paradigms: functional, object oriented and structured programming.

When the book dives into the meat and potatoes of clean architecture it is really good. Uncle Bob covers several architectural principles, including the SOLID principles which are just as applicable to architecture as to code. Various chapters are devoted to how and where to draw boundary lines in the code, decoupling and keeping options open.

While reading I kept thinking "yes, yes, I agree!". The book validates many of the ideas I have about software architecture, like abstracting databases, frameworks and other third party components and relegating them to the fringes of your program, rather than putting them front and center. As Martin puts it: the database (or framework, or the web) is a detail.

A case study and an example of the architecture of a simple game show how to apply Clean Architecture in real life situations.

The final chapter, written by Simon Brown, deals with architecture in a bit more detail and presents some options on how to divide code across architectural layers.

An appendix allows Uncle Bob to tell some anecdotes from his early career (up until the early 1990s) and how certain successes and failures shaped his ideas about architecture. While sometimes going off on a tangent, I found it really interesting, and sometimes painfully recognizable, to read.

The cover promises an afterword by Jason Gorman, but I wasn't able to find it. Is it me, or is this an omission?


Conclusion

Don't expect a book that tells you which frameworks and database systems to use. Clean Architecture is not about details like how to use Azure Services or Entity Framework 6. On the contrary, this books focuses on timeless architecture that is resilient to change.

I enjoyed reading it and can recommend Clean Architecture to anyone with an interest in software architecture.