Writing a user story

A story about how we as developers try and understand and implement what our users need

Photo by Jamie Street on Unsplash (Edited badly, by me)

A story about how we as developers try and understand and implement what our users need

One of our main responsibilities as developers is to write new feature that our users will hopefully enjoy. These features can come from any number of sources:

• The users themselves

• Our project partners

• Ourselves

In all cases, we have a hypothesis about how our users are using the site and we need to express that in such a way that any member of the development team can understand our intentions and create a solution that fulfills expectations.

Communicating the exact nature of a feature is often difficult. We have this glorious image in our mind; if only the software did “${THING}”! But retaining that image through the murkey details of development is sometimes a complex thing to do. However, through the course of my time as a developer I have identified some things that make it easier for me to understand and communicate both the stores that I would like to propose and the ones I need to implement.

Skipping ahead a little, the below is a complete story ticket in “Markdown” format. We’ll break it down into components shortly:

# As a user I do not want to have to re-enter my address.

This is a story ticket! It contains broad information about the task, but no specific technical implementation details. For that, please create a subtask ticket, and do the work.

## Project Manager

To have this work marked complete users will not have to re-enter their address during the checkout phase.
It’s expected to have an increase in checkout conversion, which we will be able to see in the conversation metric in Google Analytics.

The due date on this work is 2018-01-01

## Developer

This work is expected to take approximately 10. This has a Medium confidence. 

This will be implemented by adding the required autocomplete tags, such that the users browser will autocomplete their address. This should stay up to date, and reuse information the user has provided to other services but the browser has cached.

## QA

The environment in which this can be tested is at the URL:

https://path.to.testing.machine/

Please see any QA tickets for additional context.

In looking at it, it’s super short! This is a super nice property. Let’s break it down:

Title

As a user I do not want to have to re-enter my address.

The title adequately sums up up the user story in as few words as possible and is easily differentiable in a list of tickets in the backlog.

Explanation

This is a story ticket! It contains broad information about the task, but no specific technical implementation details. For that, please create a subtask ticket, and do the work.

This deliberately limits the scope of the ticket. We have a lot of super helpful colleagues who would like to supply as much information to us as possible. However, often that information can start adding to the story without meaning to. What started as a helpful idea by some stakeholder becomes a requirement, and the requirements start to stack up and become specific. The ticket can get lost in a mess of ideas from lots of people, and a very lost developer.

Story

## Project Manager

To have this work marked complete users will not have to re-enter their address during the checkout phase.
It’s expected to have an increase in checkout conversion, which we will be able to see in the conversation metric in Google Analytics.

The due date where required is noted in the “due date” field.

This is a suuuper nice story for several reasons:

It’s specific about the desired outcome, but not the implementation

Each developer will have their own specific way of solving the problem. Additionally, other stakeholders wish to convey their notions on how to solve the problem such that it meets their expectation and beaves in a way they’re able to predict. It is super important to convey the the proposed solution as soon as it’s known, but it should come either from or in partnership with the developer that will eventually implement the work. Otherwise, the solution might be agreed but impossible!

Consider this requirement to have the user not re-enter their address during the checkout. There are in fact three ways of solving this problem:

1. Saving the address in the application such that it can be reused next time.

2. Using the autocomplete APIs and address information already stored in the browser to fill in the address fields

3. Avoiding the checkout completely with something like the PaymentRequest API

Historically we tend to opt for the former as it’s been the only stable way to do implement this, and it’s well supported by the applications and we work with. However, #2 and #3 are now increasingly viable, user friendly and cheaper alternatives.

Should the requirement have been written something like:

The user should have their address saved during checkout

We would not be able to suggest these cheaper, perhaps superior alternatives. Additionally, we do not have the context of why the address is saved. Is it for shipping? To send mailouts? And so forth.

It clearly indicates what will be used as the definition for a successful ticket

To have this work marked complete users will not have to re-enter their address during the checkout phase.

It is sometimes difficult to determine exactly what effect a user story is supposed to have. The requirement was that a user does not want to re-enter their address, but there might be several places in which it’s appropriate for them to enter their address.

For example, the initial requirement was:

As a user I do not want to have to re-enter my address.

A perfectly valid (though somewhat intuitively absurd) implementation of this would be to ask the customer to:

1. visit the customer account

2. Fill in their address

3. Save their address

4. Complete the checkout

5. Complete subsequent checkout without entering address

However, this fails to express the intended outcome of the work. The above is flawed both in that users cannot correct their address in the middle of an ecommerce checkout and that it requires extra steps for them to achieve the required behaviour.

Accordingly, defining specific success criteria is a useful way to be clear as to what’s expected.

It defines a measurable goal that can be checked to determine if the work functions as expected

It’s expected to have an increase in checkout conversion, which we will be able to see in the conversation metric in Google Analytics.

Despite our best efforts, user research and empathy sometimes we do well intentioned things that negatively affect user experience. Consider the discussion here:

The discussion is interesting as it’s not clear whether this feature will in fact be particularly valuable. There are strong opinions either way, but the only true way to determine whether this change is a good one is to check some data.

In the example above, it might be the case that users find the new design that saves their address confusing and checkout conversion goes down. Then, regardless of the initial design the change should be reverted and thought about once again.

It communicates due dates for prioritisation

The due date on this work is 2018-01-01

Though we sometimes pretend to, we as development teams do not work in a vacuum. There are regularly marketing campaigns, internal notices or tutorials sent out to customers to make sure the changes to our software go as smoothly and profitably as possible.

Unfortunately, sometimes those date are not 100% clear when starting the work. As a result we will make a design decision that is superior in terms of debuggability and ensuring the costs of development remain low over time, but does not get completed in the time required to launch the feature by other scheduled dates.

By acknowledging the date up front all parties can see when this feature should be implemented, which in turn influences how it should be designed.

Development

Indeed, the obligations to write clear user stories do not end with the project managers! We as the development team need to build on top of our work to clearly communicate our intent and manage the expectations of other stakeholders.

Estimation

This work is expected to take approximately 10 days. This has a Medium confidence.

All changes need to be factored against an estimate, so cost vs benefit can be established. Should work be to expensive for it’s predicted return on investment it needs to be killed as early as possible and it can bump further up the priority based on whether the returns on a given ticket exceed the expected.

It should be the case that estimates are collaboratively agreed upon by all stakeholders, but limited only to the developer who is implementing the work. They are, after all, the only one who can judge their own skills and insight into a given problem.

Design

This will be implemented by adding the required autocomplete tags, such that the users browser will autocomplete their address. This should stay up to date, and reuse information the user has provided to other services but the browser has cached.

As developers we will implement a solution to a given problem. However, our solutions sometimes do not meet the expectations of those who have supplied us with the problem.

Given the above example, it could be that our solution does indeed solve the problem as advertised. However, it might be that the project owner has implicitly imagined the developer will persist addresses within the application, and has thus factored in the use of those addresses in some other work.

Communicating the design as early as possible allows setting expectations for how the feature will behave when implemented, and allows project stakeholders to build further behaviour based on their understanding of the proposoed design.

Quality Assurance

## QA

The environment in which this can be tested is at the URL:

https://path.to.testing.machine/

Please see any QA tickets for additional context.

Lastly, quality assurance needs to ensure that the ticket meets the expectations as they’re defined in the ticket. This invariably means that the ticket requirements need to be clear, as they should be before the developer starts work.

Quality assurance in our organisation serves several purposes:

1. To ensure the ticket fulfills the expectations as laid out in the ticket

2. To ensure the ticket requirements themselves make sense

3. To ensure that this work doesn’t degrade other aspects of the experience in arbitrary ways, not factored by this ticket.

Consider for example that the developer implements a solution in which data is saved whenever it is changed, as well as encourages the browser to autofill the data. The users data is then automatically saved just by visiting the page. Excellent! Or is it?

In this case, it might be that the user does not wish to communicate their address. Indeed, we haven’t got the consent required by the GDPR to ensure that this is what the user wanted and it is impossible to take back this information.

Quality assurance helps pick up edge cases such as this.

In Conclusion

Writing an effective user story gives all stakeholders a clear idea about their responsibilities, the outcome and predicted life cycle of the ticket and when the ticket is expected to be delivered. It can prevent days of labour under false assumptions and kill many “misfeatures” before they’re ever implemented. It is a skill that is worth pursuing, and I hope that the above has at least made the development perspective on such tasks much clearer.

Additional Reading

• Writing a bug report — Me.