We went through a painful outage of Atlassian products. It was difficult for engineers on both sides.

The criticism on the social media about Jira often amazes me. While some of them are right on spot, there are some others that point towards not so optimal, sometimes plain wrong usage of Jira. In this two series post, I will list both antipatterns and best practices to use Jira effectively, from my experience.

BACKGROUND

In the last 20 years, I used bugzilla, redmine, trac, github, gitlab, azure devops, kanbanize, kanbantool, trello, rally, mantis, openproject org-mode (yes, there was a time I used emacs for most of the stuff), taskwarrior to work with issues, many of them in professional settings. Some of them changed a lot in the last years (especially service based ones)

I happened to have a chance to use Jira in extremes. Many hundreds of active projects, tens of thousands of components, labels, hundreds of active workflows, dozens of custom issue types, thousands of new issues created every few days (not automatic creation, based on input from product owners, engineers, customers etc). Using Jira in a way that it helps product evolution in an efficient way was key, it was doable and being done.

On Jira

The blessing and the curse of Jira seems to come from the same point. Its flexibility and undogmatic position requires making conscious choices to decide which parts to use, which parts to avoid, and which parts to customize. It is essential that you customize it to fit your need, it is designed for that. If you are’t going to customize, use whatever comes out of the box without exploring its capabilities, you can as well use another tool.

The flexibility of Jira definitely contributes to the criticism around complexity. However, there are no two organizations that have same flow, same structure, same way of working. Therefore opinionated, rigid tools always end up creating a production planning/management environment that is detached from the reality. The visualization of the flow matching the reality is key point in managing and improving systems. We will visit those in the next post.

Let’s continue with the anti-patterns.

Jira Anti-Patterns

In this post, I will focus on anti-patterns I have seen and explain why they are dangerous. I might contradict with what Atlassian or others say, as this is purely based on my experience and observations.

1. Using time tracking

I have visited this here It stands today as well.

Unless there is a boring legal requirement to do it (eg: billing purposes), individual time tracking needs to be completely avoided. After all, it is not important how much time engineer “reports” on certain task. Because, we focus on Lead/Cycle time of the whole issue, not personal time tracking. You can keep optimizing your flows, finding bottleneck perfectly, without spending time on time tracking at all. As with all kinds of measurements, you need to think and answer the question “What am I going to do with this measurement ?”

2. Using subtasks

I am not going to make an exception on this like saying “use subtasks only when …”. Subtasks are horrible admistrative overheads that make nothing easier, more visible, or more clear. The value received by using subtask is miniscule compared to its overhead. How are subtasks typically used in the wild ?

Subtasks to define what needs to be delivered in a user story

Let’s say we have a user story that involves frontend, backend, security, deployment, documentation etc works. Some teams choose to create and micro manage those as subtasks of story. What are the problems:

1. Subtasks lack many flexibilites of stories and including estimation, in the first place.
2. Slows down the delivery because it contradicts with INVEST mnemonic of user story. Story definition that meets INVEST criteria is automatically short enough finish in a reasonable amount of time. Adding subtasks to include different aspects like above, already breaks INVEST. Having multiple subtasks like that, clearly prevents frequent delivery
3. An item that can be perfectly defined and handled in one story, ends up many subtasks that require administrative work on each for no extra benefit

Subtasks to define acceptance criteria

Again, too much overhead. Acceptance criteria should be just part of the story description, preferably in BDD format and that should be enough. If you have many acceptance criteria, it often means user story should be split so functionality can be delivered sooner, gradually, each verified by accompanying acceptance criteria. In some cases, this may also allow people to work in parallel.

Subtasks used as notepad

This is probably the worst. I have seen subtasks like write integration test, create ansible playbook, deploy playbook in server, sometimes +20 subtask like that in a single story.

Jira is not a notepad replacement. If those notes really need to be communicated, comments are better.If it resembles an acceptance criteria, it must be an acceptance criteria in the body.

3. Using one workflow, one set of (default) screens for all teams

Jira allows defining custom workflows so every single team can create a state diagram that accurately matches their reality. Whenever we focus on flows, it is always a first requirement to visualize/manage flow in a way that it matches the reality (Kanban, value stream mapping etc)

Forcing all teams to use same workflow creates a flow that meets nobody’s needs. I frequently see this in many environments and real driver is to give project owners as little rights as possible.

However, workflow customization is one of the biggest powers of Jira, and it does not have to be linear like in many other tools. Not embracing this is a huge missed value.

If you have datacenter version of Jira, having thousands of workflows might create a performance problem. But that is not a common situation.

Jira also allows complete customization of form screens. Every field, every tab can be customized for every issue type, per workflow. This is a great flexibility.

However, most Jira installations prevent teams from customizing issue screens. Therefore they end up using forms with many fields they dont care. When they really need a certain field there, they ask it to be added to common screens and then we end up screens with full of fields that are meaningful only for a single team.

In reality, only few fields are common for every team. Customizing screens allow engineers to use forms with as little fields as possible.

4. Tracking automatable tests

Some teams keep creating test issues for every release, over and over. They spend time on manually entering fields there, test results etc and then closing one by one. I have never seen a frequent releases happening in such teams, not surprisingly. Except few branches like exploratory tests, all tests need to be written and executed programmatically anyway. Using test issue types or plugins around test management, will not make software engineering any better.

5. Integrating Jira too tightly to deployment process

It is very tempting to connect everything together, building a perfectly working system, like mesmerizing swiss watch mechanism or a mechanical astronomical clock. But it is the rainy days that test our waterproof. We integrate Jira for many otherwise manual work and it is often quite easy due to large amount of high quality integrations.

However, ability to build, release and deploy software is absolute minimum functionality we would like to maintain.

Jira, or any other roadmap management tool does not play a functional role in that in a way that it is observable to stakeholders. This does not mean that issue management tools are unnecessary. It is impossible to manage business.

Therefore, integrating Jira (or anything similar) with the delivery in a way that it becomes impossible to work when there is a problem on that, is a huge risk (As some experience now) The integration should be there, but with an easy escape hatch.

6. Misusing fields

Although Jira supports adding many types of structured and non structured fields, most setups prevent people from leveraging this. This causes teams to abuse existing fields for purposes other than the real purpose of that field. Once a field is used in a different context than others, this creates confusion amongst people since they understand different things when they look at that field.

Misusing labels

Labels are escape hatch for most people. Combining with the power of JQL, one can achieve a lot just with labels. However there are cases where fields (existing or custom) are more appropriate. If a certain label becomes a structural part of the flow (that is, not an ad-hoc thing for a temporary reason), then it usually makes more sense to create a field for that so we can have control on allowed values, types, optionality etc. Using labels to mark dates, versions, teams etc are practices that often becomes continuous administrative load.

Misusing epics

Epics are logical grouping of stories based on a higher level goal with due dates on delivery, helping longer term roadmap planning. Using epics like “linux”, “security”, “devops” etc completely defeats the purpose because they don’t track a higher level goal.

Another antipattern on epics is keeping them open, like forever. Similar to user stories, we should be able to close epics in a reasonable time frame. That time frame changes from organization to organization. In my opinion, no epic should stay open longer than a quarter. Also, the content of the epic can be finished in less than a month, the administrative overhead of epic may not worth it.

Why maximum 1 quarter ?

• If you have OKRs, they will be mostly designed for quarters. Aligning your higher level planning with that, may help seeing the bigger picture better.
• Often, it loses the steam, traction when epics are kept open longer than that.

7. Creating issues automatically, but closing manually

Jira, like many others, often gets integated in to other systems so issues can be created automatically. This is fine, only if you also close those issues automatically too. Otherwise, people have to own the closing step for all those and this again creates an overwhelming administrative work.

8. Inflation of issue links

Issue links are useful to keep track of relations between issues. Defaults ones are self-explanatory. However I have seen some practices of creating increasing number of issue links that are slightly different (if different at all) from the others. Issue links are useful only when they are uses consistently because otherwise JQL based filters and queries may be more difficult to write, and give wrong results.

9. Focusing on less useful (if ever) reports/gadgets

Jira supports out of the box many gadgets and reports. That does not mean all of them are useful and necessay. Users need to find few most important ones and leave the rest away from immediate view. More reports and gadgets you try to follow, more dilution in your attention and more risk of monitoring fatigue.

The best reports are the ones that correlates directly with your business impact, any kpi/okrs you have. Here we must note that, if kpi/okrs set wrong, Jira (or any other tool) will not make them magically meaningful.

10. Directly using Jira rest api

Although Jira has rest api, it is not an easy one to use. Most of the criticism for that is correct. The complexity of the api is also caused by its flexibility. However, there are many cli tools and abstraction libraries for Jira. Rather than trying to consume the api directly, it is faster/easier/safer to use one of those.

Conclusion

Jira is one of the oldest, mature issue tracking systems and its widespread use includes critical businesses and engineering teams that release frequently at stable quality as well. Its flexibility and vast features are often causing confusion and difficulties in getting started with. If Jira is chosen, it is best to learn its full features and customize to fit your own flow. Otherwise, combining with the anti-patterns above (and there are more), the benefits will be very limited.

I have not included the point: “Using Jira when it isn’t needed” because that is more of a initial decision mistake. Indeed, if a team is able to consistently deliver business value, able to improve its way of working, able to pinpoint the bottlenecks, able to make data driven decisions on the roadmap without using Jira, and if the team doesn’t feel anything lacking, then there is no need to solve a problem that doesn’t exist.

There are few points which I would love to see in Jira, but I will visit those in the next post where we can visit some best practices (again, from my point of view)