Unfortunately This Post is About a Jira Template

Consider the humble coffee machine, and its uses: It's great for making coffee, and in some instances, depending on the type of coffee machine it is, it might be useful for making tea and other hot drinks. Maybe even cold ones! Critically though, a coffee machine is not the right tool for making things like pizza. If you have a coffee machine, and desire a pizza, you owe the coffee machine nothing and should not feel guilty using another tool to make your pizza.

That may seem obvious, but I don't think that framing – what is this tool, is it useful for my purpose – is always quite so self-evident. Consider that in software development there are many kinds of tools: programming languages, frameworks, CI/CD platforms, etc.. But there are yet more beyond those: a team structure is a tool, a contract is a tool, a team role is a tool.

For every tool, it's important to ask questions: what is this tool intended to accomplish? What purpose does it serve, and at what point is it no longer useful? Is there a tool better suited to the task at hand?

Background

As previously mentioned, on my most recent project I was the full-stack application team lead for a web app intended to give customers visibility into orders they had placed with my client. As app team lead, I was responsible for being the technical leader of a team of 8-10 developers across BCG, the client, and contractors, as well as contributing daily to the code myself. Working alongside my dev team were two designers and two product owners, all from the client.

Early on, when the project was in the whiteboard stage, the product owners from the client began writing user stories for the project. Despite how early that process began, it was a very helpful exercise, and as I've written previously, even a strawman¹ of "what are we actually doing" is helpful. But I noticed early on that the story quality wasn't where it needed to be.

The Problem

Anyone who has learned about Agile, or worked in a software team or an Agile project, is familiar with the user story format "given/when/then" (also sometimes written as "as an X I want to Y so that I can Z." Hereafter referred to as the "gherkin format.")² The gherkin format is intended to help make stories easier to write for business users, and easier to consume for technical users.

I admire the idea of a user story format intended to be simple, broadly applicable, and which can be used to describe both features and tests for those features. But consider the gherkin format as one of the tools your team could use – like any tool, it is possible to misapply out of either a misguided sense of loyalty to the tool, or misunderstanding of its purpose. This is an important framing, and as I said in the intro, we owe it to ourselves to consider when a tool is right for the job, and when we're stretching it beyond its capabilities.

Failings of the Gherkin Format

Because the gherkin format is so simple, and the stated benefits are so far reaching ("Wow, I don't have to write separate test cases for QA? I can write one story per feature?") I have observed that some non-technical story authors are more likely to start defining requirements with the gherkin format template than to start with the need of the business and the capability of the development team. This results in the kind of user story I saw a lot of at the beginning of this project (and yes, this was the entire story):

Given I am on the home page, when I use the search bar to search all of my orders, then I see search results for each of my orders .³

Ask yourself: did the gherkin format serve it's purpose here? Here are the questions a developer might have after reading this story:

1. Does this story assume the home page has already been created, and where is the user story for the home page?
2. Do we have a design for the search interaction, and what components do we need to build on the frontend to support this design?
3. How many results should I see?
4. What interactions are possible on a search result?
5. How do we handle errors?
6. What is the maximum time allowed for a search?
7. Do we need a typeahead/autocomplete feature?
8. If we answer all of the above, will this still be an atomic unit of work?⁴

Let's say for the sake of argument, that we tried to make this work in the gherkin format. Here's a better version of the story, with several "gherkin" requirements:

Given I am on the homepage (ticket 1234), when I type in the search bar and hit enter, then I see a loading spinner (ticket 9921).

Given the search API (ticket 4567) returns results, when a maximum of 10 seconds have passed and they are loaded, then I see a search result row (ticket 7890) on the page for each result, which can be clicked to go to that order's page (ticket 3322).

Given I am typing in the search bar, when I have entered more than 5 characters, then I should see potential matches for my query in a dropdown below the search bar in no more than 3 seconds.

I think this version actually illustrates at least one problem with gherkin more – these aren't easy to read sentences. They weren't easy to write! Still, we've made some improvements:

1. We described several requirements of a search feature, not just the search feature generally.
2. We denoted the dependencies of this ticket by marking in the text the other tickets that need to be complete before this one can be started.⁵
3. We have defined at least a few clear technical requirements:
   1. Search bar calls the search API,
   2. Search takes no longer than 10 seconds,
   3. Search autocompletes above 5 characters and within 3 seconds.
4. The requirements are now non-overlapping such that you can start to imagine individual tests for this feature, rather than a single behavioral test.

However, the key reason this story was easy to improve for me is that I have experience building frontend applications and component libraries before! For a person who is non technical these improvements may not be as obvious.

Furthermore, let's go back to how easy they are to read: it's clear that I was writing to the template. Again I'm sympathetic with the format's goals, but if the reader and writer have to bend out of their way to understand and use this format, then it doesn't do a good job of translating business requirements spoken aloud into actionable writing.

In Search of a Better Pattern

So what did we do to improve story quality?

Firstly, and most importantly, I devoted over half of my time as team lead to product owner support and interfacing with the design team. I didn't plan to do that from the beginning, but it became clear almost instantly that one of the reasons stories were so sparse was the lack of a technical voice in the room when work items were being brainstormed.⁶

Secondly, I started thinking about what was missing from the gherkin template:

• Context: why was this story written in the first place? What is the background for why this requirement was decided upon?
• Clear objective: What is the plain-language goal you want me to accomplish by doing this work?
• List of requirements: I know that the business will always lay out at least a couple of hard requirements for a piece of work – what are they? Any hard limits on timing, concurrency, etc.?
• Links to supporting materials: Is there a design I should be referencing? Any documentation I should look at, or notes from another developer?

A New Template

Here's what we ultimately settled on after a few iterations:

Notice that the template has more direct prompting along each of the axes I called out as areas for improvement earlier. Let's take a look at each section in turn:

• Context: I like to describe this section as "explain why you asked me to bother getting out of bed this morning." Give me an idea of how this item of work came to be. Some examples of prompts for this section:
  • Was there something wrong with previous work?
  • Did an assumption we made previously turn out to be false?
  • What did we learn from user research that resulted in a new item of work?
• Objective: This is where you explain, in plain language, what it is that you want done. Doesn't have to be long, and often, was only a single sentence.⁷
• Design Link: Included here so that after someone reads the objective, they can immediately flip to the visual design in order to see what the intended output looks like. For more backend, data, or other non-visual work, this won't be needed.
• Acceptance Criteria: Freed from the burden of the gherkin format, you can now just straight-up list out your requirements. This part of the template was always a bulleted list of requirements and sub-requirements, including things like "if a user enters X, respond like this" or "must load in no more than 10 seconds." If the ticket is a spike ticket then the requirements might be to write more tickets, or to produce written research documentation or other output.
• Technical Notes: Often as tech lead, I was referencing technical documentation when I provided input to the story. No sense in asking another dev to dig those docs up – might as well link them directly. Then I could also provide commentary on that documentation if necessary.

And here's a real example of an early ticket after we implemented the new template:

Admittedly this ticket is pretty technical, but that's the idea! Parts of it can be written by the product owner, and parts need input from the tech lead. Many, if not all, of the tickets we worked on required one pass from the relevant PO and one pass from me to add color and technical details.

Impact

One of my proudest moments on the whole project came shortly after we implemented this ticket framework. A brand new product owner at the client came to me asking advice on new tickets he was writing. He had previously struggled with user stories – and indeed, had written some that were like our first, extremely minimal example – but now the ones he presented were a lot clearer even on his first pass!

I complemented him on his improvement and he credited the new template immediately, and said (paraphrasing): "This new template actually makes me think about what I want the team to do, and why I want it. It also forces me to write more, and that writing helps me think through what I'm asking more completely."

Another benefit: It was far easier for the developers to see when they should be done, because the list of acceptance criteria functioned like a checklist that was agreed upon by the PO and the dev team. It also made tests easier to write – a supposed advantage of gherkin!

One unexpected benefit of this format: stories became more atomic. As the list of acceptance criteria grew beyond a certain point, it was easy to see where to break a story up into multiple. Oftentimes in refinement, as questions about a story were asked, the list of acceptance criteria would grow until the team visually saw it was time to divide up the work. That also mean we had an immediate list of ACs to divide among the two tickets, making that division easier.

Downsides

It's obvious that one of the downsides is the verbosity – I like to write but most people do not. Even the aforementioned junior PO who was writing much more with the new template ultimately wrote far less than me per-ticket. But in my opinion there's no getting around the fact that the folks describing the work have to invest the energy in making that description comprehensive, easy to understand, and lasting.

Another drawback: the template wasn't a silver bullet. The biggest issues we had following the introduction of this template couldn't be helped by it: POs were stretched thin and weren't technical and/or didn't have significant digital project experience, and I was splitting 120% of my time across PO work and hands-on coding.

Final Thoughts

Can a Jira template solve all your problems? No, what can? But thinking critically about your tools, including your process and work tracking tools, can help encourage better working habits and smooth interfaces between teams. Ultimately this template led to far less friction in refinement, planning, and execution of my team's work, which I consider to be a fair trade off for extra time spent writing.

Footnotes

1. (noun) Consultant lingo, meaning "initial stab" or "first pass at something," intended as a jumping off point for a further discussion. May also be called a "SWAG" (Stupid Wild Ass Guess) if predicted to be particularly controversial or very little is known about the subject.
2. I have heard this called the "Gherkin" format, I think based on the idea of turning user stories into Cucumber tests.
3. This may seem like an extreme example, but this is lightly edited from a real user story I remember appearing on Jira in the first weeks of our project. There were no further requirements, nor a link to the design.
4. I'm a strong believer in the atomicity of stories – each story should be completely discrete and non-overlapping. If two things need to be done at the same time, that's one story. If there's a dependency between two things, that's two stories and we link the dependency. If we think broadly speaking two people can work on it at once, break it in two along those lines, etc. etc.. Without focusing on story atomicity, you risk creating stories which can spiral into very large rabbit holes, and this negatively impacts velocity estimation, team morale, and consistency.
5. This isn't really a failing of the gherkin format, but it's illustrative of the kind of requirement that can be lost if the story author gets the dopamine hit of satisfaction from meeting the template. Once you get the emotional hit from "I did it, I wrote the story!" it's easy to forget to do the administrative work of linking dependencies, tagging folks, etc..
6. This is one thing that's easier in a consulting context: at BCG we don't really define hard and fast roles for each team member, so it was easy for me to tell my leadership: "I'm going to be spending 50% of my time on product" and for them to say "ok, sounds good." In a project where the tech lead doesn't have this flexibility, it's up to the product team to get it right without as much technical support.
7. Often many of us found that the last sentence of what we planned to write for the context became the objective naturally.