• Seilevel Team

    Here’s the Team

    Welcome to our Seilevel Photo Op.

User Stories and Technical Stories in Agile Development

A common problem that I have seen Agile teams grapple with is writing user stories and acceptance criteria for projects that are heavy on technical implementation and modifications with no substantive change in the user interfaces or workflows. This kind of scenario is very common in companies that are upgrading infrastructure or changing underlying design and architecture to improve performance or scale. These types of projects are typically referred to as ‘IT Driven Initiatives’ to distinguish them from projects done in response to some specific functionality requested by the Business team.

The User Stories written from the viewpoint of the functionality that users will need does not really provide context in terms of the work to be done by the development team. In most cases, the existing functionality will satisfy the needs of the user with no additional changes needed. The changes are taking place under the hood, as it were. Teams in these situations create user stories that are nothing more than technical implementation details. For example, it is common to see stories like this:

‘As SYSTEM A, I want to map the incoming Order XML to the main Canonical, so that SYSTEM B can consume the Canonical and run order validation rules against it.’

The acceptance criteria that are provided for a story like this will be filled with technical details on the Order XML, Canonical, validation rules and so on that need to be delivered.

The problems with this approach are readily obvious. There is really no context of what functionality is to be delivered from a user perspective or the expected outcomes from their viewpoint. An entire backlog filled with stories like this can easily become incomprehensible, especially in complex environments. Very soon, developers have no context of what they are building and most importantly, how it is going to be used eventually from a user perspective.

At Seilevel, we recommend using Technical Stories instead of User Stories in these situations. Technical Stories are best used in conjunction with User Stories, to complement them. The User Stories provide context to the associated Technical Stories so that the developers understand the functionality from the user viewpoint.

Continuing with the example above, it can be reformulated as a User Story / Technical Story combination as follows:

User Story: ‘As an online shopper at ACME Widget Company, I want to ensure that my order is complete and valid when I submit it at the online store, so that I can get the products I ordered in a timely manner without mistakes or delays.’

Technical Story: ‘In Order to ensure that only valid orders are accepted by the system, System A must map the Order XML to the main canonical and provide the main canonical to SYSTEM B to run order validation rules.’

In a real world scenario, there will typically be multiple Technical Stories needed to deliver the functionality required by the User Story. Technical Stories can be as granular and detailed as needed to ensure that the proper functionality is built. However, they will all tie back to one user story that the developer can quickly lookup to get context on why they are performing the tasks they are engaged in.

I typically tend to write the User Stories in these situations at a higher level or even use Epics, if appropriate. The Technical Stories are written targeting the team that will work on specific pieces of implementation or specific sub-systems. Acceptance Criteria are written to be appropriate for the context of the story – User or Technical.

For example, Acceptance Criteria for the User Story could be along these lines:

AC 1 – User must get a message if the order is valid that it has been accepted for processing.

AC 2 – User must get an error message if the order is invalid with prompts on the issues that must be fixed before it is accepted for processing.

And so on…

Similarly, acceptance criteria for the Technical Stories can be written appropriate to their context. For example:

AC 1 – The data from the Order XML must be mapped into the main canonical in accordance with the mapping shown in the attached spreadsheet.

AC 2 – Main canonical must be passed to SYSTEM B via interface A using API K and a success message received when the transfer is complete without errors.

And so on…

When the stories are split out like this, it becomes very easy to test the delivered functionality. In our example, simple regression tests can be written for the User Stories to ensure that the end user experience is consistent with current state behavior. Tests created for the Technical Stories will be qualitatively different and focused on functionality at a much lower level.

In conclusion, here are the key takeaways.

  1. Keep User Stories focused on the user experience and outcomes.
  2. Write Technical Stories to give context to the User Stories from a system perspective.
  3. Map Technical Stories to User Stories so that it is clear how the functionality being developed relates to the user experience.
  4. This technique is very effective for projects where the user experience or user interface does not change but the underlying technical infrastructure is being changed to improve performance, upgrade technology or other technical reasons.

Need a free consult to work out an issue like this? Contact us to discuss.

13 Responses to User Stories and Technical Stories in Agile Development

  1. Tushar November 18, 2016 at 12:07 am #

    Hi, thank you for this post I agree with you that most common problem that I have seen Agile teams grapple with is writing user stories and acceptance criteria for projects that are heavy on technical implementation and modifications with no substantive change in the user interfaces or workflows.. very useful information

  2. Warren December 15, 2016 at 4:53 pm #

    How is a technical story that is separate from, but related to, a user story different from a user story with associated technical tasks? In the case of your example, how is the technical story different from the following list of technical tasks?:

    * Map System A Order XML to main canonical
    * Provide main canonical to System B to run validation rules

    I think you’ve provided a viable answer, but it strikes me as being an alternative for what I understand to be the traditional way of elaborating the details of a user story. I’d appreciate any insight into the difference.

  3. Bob LIeberman September 20, 2017 at 5:32 pm #

    Ajay, I guess I don’t like this approach. Never been a fan of technical stories because they reinforce the development team’s already strong tendency to see work as build X build Y rather than solve customer problem 1 and customer problem 2.

    The vertical slicing approach solves the problem in a different and often better way. You devise a “tracer bullet” as its often called, which is a full stack story having minimal functionality at all the levels except the one where the technical work is. This captures the technical work and has the advantage of exposing the supposedly “done” technical component to real-life usage by a customer, if in a limited way.

    Could you comment?

  4. Ajay Badri November 4, 2017 at 10:01 am #


    Thank you very much for your comment. We are talking of two different approaches to solving the same problem. The reasons that I use the Technical Story approach as opposed to your preferred method are as below.

    1. I want to be very prescriptive of the technical approach to be taken to design or redesign a specific piece of functionality. This is typically done after consultation with the Enterprise or Solution Architects who are designing the system and the Technical Stories capture their design approach.
    2. The technical changes being made impact all or a significant portion of the ‘user accessible’ functionality that sits on top of the technology stack. For example, a complete redesign of a Loan Application and Adjudication process. A project of this nature can easily stretch out over two years or more, depending on the complexity of the underlying system being changed. Writing user stories for each step of the process and then associating technical stories at specific points becomes very inefficient from a time and effort viewpoint. In these situations, I will typically write User Stories at the level of an Epic or Feature and associate multiple Technical Stories with them.
    3. I want the Technical Story to be tested to ensure compliance with the specified design. Since the overall functionality does not change, tests of the functionality from a user viewpoint will not guarantee that the functionality was implemented as designed – unless it is broken of course and nothing works as expected :). When there are hundreds of specific technical implementations to be tested in the lifecycle of the project, it is a lot easier for the test teams if they are dealing with the actual implementation expectations in story format with the containing User Epic or Feature providing context and baseline information.

    We can get there with your preferred approach and if that works for your organization, stick with it. But there will be a point where I believe that the ‘tracer bullet’ approach will not scale anymore from the viewpoint of the analyst who has to create the underlying artifacts – user stories and technical stories. If you get there, give this approach a shot and see if it works for you. Thanks for the comment and keep the conversation going.

  5. Ajay Badri November 4, 2017 at 10:20 am #

    Hi Warren:

    Apologies for the belated reply. I guess I missed the notification of your comment earlier and saw it when Bob commented a couple of days ago. But, better late than never, so here goes…

    I write Technical Stories in very specific situations, typically when there is a rewrite of an existing system with very minimal or no change to the functionality at the user accessible level. In these situations, I care about the very specific way in which a technological implementation or change is made. If we were to take the most basic interpretation of a user story in the context of a backlog, when the functionality already exists and has been in use for several years, the development team will be well within their rights to reject the story since it has already been delivered years ago. We get around this by giving them a Technical Story that spells out clearly the change to be made in the technology stack even though the overall functionality is unchanged.

    Further, by writing a very prescriptive Technical Story I can ensure that the test teams sign off on a very specific change that will not be visible at the user accessibility layer. This is particularly important in large scale technology refresh cycles where the changes build incrementally over time. If the initial implementations are not per the design then later changes will need to be modified or in a worst case, not possible at all depending on what was done initially. In these scenarios, the Technical Story is the ideal artifact to communicate these intentions to the entire project team.

  6. Ajay Badri November 4, 2017 at 10:27 am #

    Thank you very much for your comment Tushar and glad you found the article useful.

  7. Prasoon January 8, 2019 at 2:49 am #

    Hi Ajay,

    Found article very helpful & relevant..appreciate your efforts to respond queries /clarifications

  8. ankit shivhare March 8, 2019 at 12:08 am #

    Hi Ajay, It is late read but it helps. Being a Business Analyst I do not see any importance for writing a technical user stories since they may not be testable. The approach should be to have the solution in place for building system but not to complicate it using the technical user stories. What if solution changes and in between the sprint somebody need to spend the time to update the user stories.

    Any ways just wanted to clear the thoughts on:

    Q1: Who spends time in writing the user stories?
    Q2: Are they testable from your pov?

  9. ankit shivhare March 8, 2019 at 12:09 am #

    Hi Ajay, It is a late read but it helps. Being a Business Analyst I do not see any importance for writing a technical user stories since they may not be testable. The approach should be to have the solution in place for building system but not to complicate it using the technical user stories. What if solution changes and in between the sprint somebody need to spend the time to update the user stories.

    Any ways just wanted to clear the thoughts on:

    Q1: Who spends time in writing the technical stories?
    Q2: Are they testable from your pov?

  10. Nirman Doshi May 17, 2019 at 8:59 am #

    Found this article very useful, and yes, having technical story in the backlog makes more sense in the scenarios you have listed. Along with that, project setup (that is, creating a solution, designing bare minimum project classes, etc) are key activities for any project and starting point of development. I am not sure if it is even possible to write in a form of user story which business can understand. Also, it is not testable. And so, I would prefer to use your approach in this case.

  11. Ajay Badri June 29, 2019 at 1:36 pm #

    Hi Ankit:

    Thanks for your comments and viewpoint. Please find below my responses to your questions.

    1. The analyst(s) who is working on the project will write the Technical Stories / Features. Depending on the size of the organization and the way teams are structured, it could be the same person who creates the User Stories / Features and the Technical Stories or an analyst attached to the development team will write Technical Stories / Features and associate them to their related User Stories.

    2. Yes, both the User Stories and Technical Stories will be testable. In the scenario I provided in the article, the User Stories will be tested as part of standard user acceptance testing or regression testing (assuming that there is no functional change and only an underlying technology change). The Technical Stories are testable at a granular level during the development phase.

  12. Vijay July 17, 2019 at 1:53 pm #

    Can you please provide a sample technical story which includes interface request and response data mapping etc. along with other technical details such as the security protocol etc. In a traditional way, we cover all of these details in a system interface document which typically include technical flow diagram, request/response data mapping, samples, schema/wsdl etc. So wondering how to cover such as details part of technical user story. Sorry for being too detailed. I am pretty new to this approach.

  13. Ajay Badri August 25, 2019 at 2:01 pm #

    Hi Vijay:

    Thanks for your question. To clarify, I am not suggesting that Technical Stories or Features are a substitute for a system interface document, technical flow diagrams, request / response data maps, etc. This is not an either / or proposition or mutually exclusive set of artifacts.

    Think of it this way – the technical story or feature written at a higher level can be fleshed out by lower level stories or other artifacts that you have listed in your comment. For example, a Technical Feature / Story can be written like this – IN ORDER TO enable a sales user to submit valid orders for processing / shipment, the Order Domain WILL NEED TO provide a verification solution that will test all orders for validity prior to acceptance, SO THAT only valid orders are accepted for processing.

    This Technical Feature / Story can then be elaborated with a system interface diagram, interface mapping, validation rules, and so on to deliver the requested functionality.

    I hope this helps.


Leave a Reply

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