User Stories and Technical Stories in Agile Development

ArgonDigital - enterprise automation experts

Share This Post

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 ArgonDigital, 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.

More To Explore