Writing technical stories and epics

»My dev story does not make the sprint and my technical epics do not make the roadmap therefore important work is not carried out.« ~ Developer.

Balancing product-driven with developer-driven priorities is in some way the eternal struggle in software companies since the dawn of modern computers. The internet has plenty of blog posts on this and each company has a very specific version of it. It's a complex problem with many moving parts, conflicting interests and priorities.

But.

I vote that we keep critical and open minded about the quality of our communication as I think there is always room for improvement to make our efforts more transparent, understandable, traceable and in the end help to get them prioritised. For that we should take a look at certain aspects of how we write technical epics and stories. This short guide aims to uncover some insights that we learned by experience and by taking the position of the »devils advocate« on how we formulate requirements. And hopefully some guidance to overcome them.

The empty driver seat

This affects mostly epics – or put differently: Big long term goals – but it can also apply to individuals stories in our backlogs. An issue can only make the sprint or the roadmap if there is clear ownership and an individual that drives the issue. If you find an issue to be important enough to be pursued consider whether you might be that individual. Let's be clear: It will cause additional work, communication with other parties and for epics it's a marathon, not a sprint. Otherwise the equation is simple: Zero ownership equals zero progress. What is the responsibility of an owner?

Being able to explain the scope of an issue to the team and stakeholders
Being able to explain and back up why an issue is important
Making sure it is considered for Planning in the first place
Responding to feedback and questions from other individuals

How much is the fish?

As any other issue in our backlog technical items are investments. Investment as in money, time spent, priorities. A way to express investment is an estimate in story points. Another way is to give details on the steps required to achieve the goal. This is also a great way to sharpen the scope of your story and identify whether you're writing up an epic or a story. You can do peer reviews with other team mates or try to estimate it yourself. If you estimate a story not to be achievable in a single sprint you're probably writing an epic.
Always remember that product owners and managers have to balance a variety of investment opportunities that come from all over the place: Customers, internal roadmap, internal departments, security audits, developers and more. If an issue gives no clue about the necessary investment it is much more likely to be put aside.

Without data, you're just another person with an opinion

This great quote by Edwards Deming is closely related to the previous symptoms. When you try to put a number on an issue or epic you should probably ask yourself how to back up your impression, thus converting your opinion to fact. This is especially important when no obvious customer-facing value is added. In planning situations you can typically expect some of the following questions:

Why is technology X better than technology Y?
What's wrong with technology Y except it's not bleeding edge?
How does this help shipping new features?
Is this security relevant?
What will improve for our customers?

If you cannot answer any of this then your story's or epic's chance of getting prioritised dramatically decreases. One obvious strategy is to provide numbers:

»Our infrastructure is constantly at 85% load with increasing number of OOM issues since March«
»Version 3.4.2 has a critical security issue and is not supported anymore since 2015«
»Blog post X showed that the build time using Technology X improved on a large Angular app by 50% thus we can save 50% of our Github Action minutes«

If you cannot provide any numbers, then something is in the bushes.

The lack of goals and actionable items

When we read up on a new issue in the backlog brought to our attention by the PO we expect that it has acceptance criteria (»What do we want?«) and bugs have actual and expected behaviour (»What do we expect?«) along with a broad range of additional information such as how to reproduce a bug, UX designs, etc. The combination of those makes an issue actionable. For developer-driven issues this is not always the case. We sometimes focus too much on describing the problem in detail but not the desired state – alias the acceptance criteria, the expected behaviour, the design. In essence we should lay more weight on what we want to achieve or what to do, not why the problem exists.

The elephant in lamb's clothing

This is typically a result of one or many of the previously described symptoms. You might have several technical stories in your backlog that are actually epics. On top of this we sometimes have epics that are even multiple epics. Once you analyse your story more thoroughly (breaking down actions, identifying key success factors, obtaining data, estimating the story) you have a great inner feedback loop how big your investment will be.
Epics have different properties than issues. Most importantly: They need to be planned differently (for example via your roadmap during quarterly prioritisation) and they really – really! – need a persistent driver of the topic. Once started the progress is usually not tracked during Backlog grooming and Planning (story only) but rather in recurring experts meetings or weekly management-level or OKR meetings.

Who you're talking to?

»The on-call engineer found via the resilience metric that the core module responded with too many 500's which typically happens when the RO transaction in the event subsystem has not been flushed correctly after the hibernate adapter session terminated.«

If you noticed that this text is pure gibberish: Good for you, you're a developer. But most of the times the reader of your issue is not. That does not mean that you aren't allowed to put technical nitty-gritty into your story but somewhere in the story (ideally on top) there some sort of a mission statement / management summary / TL;DR / »As a user« section that sums up the core ideas for the people who have to prioritise what you propose and might not be working as developers for several years.

That being said another aspect of this is to generally raise awareness and educate towards the PO or product teams when we observe critical technical debt, architecture quality or performance issues. These are all important non-functional requirements of a product and should be treated as such. Again this puts more weight on the fact that we should think about the user benefit of solving an issue.

Balancing impact and effort

Sometimes we find ourselves observing problems occurring on a regular basis and we write up a problem description and a potential solution to it. We should ask ourselves how big the impact time-, money-, resource-wise of the fix would be and, in comparison, how much effort it requires to get there. We might identify that this is not in a healthy balance and thus also can affect the likelihood of getting prioritised.

An example would be a recurring production issue that has a safe and easy mitigation, e.g., just redeploying a service without downtime that requires two clicks. If the solution to the root cause is to break a public API or rewriting the persistence layer to save those clicks it is hard to argue why we not just automate the detection of this failure state and its mitigation – in this case a safe redeployment. Don't get me wrong: We have to be careful on our decisions towards technical debt but you might find yourself in a situation where it might be better to be done than to be perfect.

One way or the highway

Prioritisation in its essence means compromise. Whether we want it or not we cannot do everything what we would like to do. With this in mind you might want to spend some time on thinking creatively about your proposed solution. Is it the only solution? What about we discontinue a whole product feature and remove a piece of technology instead of replacing or improving it? Can we trade technical complexity with functional scope? From experience I would say »wiggle room« is a good tool to prioritise technical work.

The lone wolf

As with compromise we should also allow to incorporate feedback cycles into the process of refining issues that are important to us. A great tool for that is »Rubber ducking« or peer reviewing your problem and proposal with other developers. Not only will it help you to find more ways of explaining, simplifying, isolating, solving your problem but the more people understand the value and impact of your proposal the more visibility it will get and – best case – more ownership.

Jira Walhalla

There are sometimes issues that are just put into some ethereal place in Jira where nobody looks. Like a closed Epic, a deprecated Epic or none at all. This heavily influences the visibility of your issue as this even removes the possibility of stumbling upon it by someone else. Most of the prioritisation happens in certain places in Jira: The next sprint's backlog, a roadmap epic, the Team's DEV bucket. If you're unsure just ask the PO or Lead of your team as they should have a high-level overview where stuff is tracked.

Published by Basti Tee

Visit author page