How to use Jira for Analytics

This article is designed to provide some tips for how to use Jira when creating and updating tickets. If you haven’t already checked out my article about “What Jira is and how you should be using it”, I’d highly recommend giving it a read. There are some crucial points to frame your mind around before diving into Jira. Without the right frame of mind of who will be using your Jira tickets, your ticket will probably be subpar and at times almost useless, not to mention that you’ll probably find yourself frustrated by your manager who is asking for various updates because information isn’t making it’s way from your mind to the ticket. Okay, with that disclaimer, let’s dive into how to use Jira at a basic level.

Creating your Jira Project

The first thing that you’ll want to do is create a new Jira project if you don’t already have one that you’re working with. There are about 5 different ways to accomplish the same task in Jira and how you use Jira can change depending on your organizational structure. What I’ve designed at one company didn’t always work at a different company due to how Jira would be adopted, how management would use it, and how reporting structures were designed. Sometimes you might want to design some of your Jira views around a massive team, other times you’ll want to design around a smaller team, and sometimes you’ll choose to design Jira around a project instead of any specific team at all. Most of the time when I configure a Jira project I do so based on the people that are on my team because I need to manage their projects.

What are tickets

The primary feature of Jira is a ticket. Tickets are basically tasks that need to be performed and there are many different types of tickets that can be used to help you organize all of your tasks. Some tasks are small and can probably be accomplished in a matter of minutes. Other tasks might be very large, requiring many days, weeks, or months of work. They can be complex in nature and can have different people working on all of the smaller task items that when combined will produce a completed project.

Creating Tickets

There are a few different ticket types that you should be familiar with. Keep in mind that Jira is highly customizable so you may see something slightly different in your environment. If you have any questions, please check with your internal Jira administrators.

A ticket should be a singular subject of work and have a clear summary of what needs to be accomplished. The amount of effort that it will take to complete the task, the people that will need to perform the work, and the complexity of the work will dictate the type of ticket that you will need to create (more about this in a minute). Ultimately, each ticket needs to have an assignee attached so that someone is responsible for completing the work.

Ticket types

• Epic — An epic is a large unit of work and this ticket type is typically used as a ticket to collect other tickets. For example, if I have a project to build a dashboard, I might choose to use an _epic_, ticket type with the subject of “Build Dashboard for Monthly Revenue”. On the surface one might suggest that creating a dashboard is easy and isn’t a large unit of work. While this could be true, I find that rarely find a task like this to be so simple as there are a lot of moving parts.
   
• Task / Bug — Task and Bug tickets are pretty common and in my mind they are basically the same thing. They are a small unit of work for an individual to complete. A task or bug ticket can be part of an _epic_ or they can stand alone and not be a child of an _epic_. Some people choose to create a custom ticket type of a _bug_ because it can be used to classify tickets and use different workflows. This topic is a bit more advanced so I’ll gloss over it for now.
   
• Sub-task — A Sub-task is a ticket that is a child of a task ticket. There can be multiple sub-tasks under a Task ticket. How and when you decide to use these is really at the discretion of the team. I’ll give an example on all of these tickets in a moment.
   
• Story — This type of ticket is much like a _task_ ticket but it is just labeled as a different type, which is useful if you’d like to configure custom fields and workflows when users attempt to create a user story.

When it comes to selecting your ticket type there are many different options to choose from. In most of my Jira configurations I choose to keep things very simple and I avoid lots of custom fields, flows, and screens because I seldom find all of the customization to be worth it in an analytics environment. However, when I’m working in a software development environment I do prefer to have more customization due to the level of quality assurance, protection of our code base, and many other moving parts. Analytics teams could benefit from these flows but I have always found that it’s challenging enough without the additional features to gain adoption and train users to and make quality comments.

Practical Example — Creating a Ticket

Here are a few examples of how I create tickets. Let’s say that I have a project to create a Monthly Revenue Dashboard. I need to create a ticket for the Monthly Revenue report but which ticket should I start with? My options are to use an Epic, a Task, or a User Story. I tend to avoid using User Stories because I feel that a Task or Epic will accomplish the same thing. So how do I decide if I should use an Epic or Task? Part of this decision depends on the number of subtasks that will be involved. If there are zero or maybe just a couple of sub-tasks, I can probably use a Task ticket and roll all of my sub-tasks under the Task ticket. However, I have a large number of sub-tasks, I might create an Epic ticket and possibly have five or even twenty Task tickets that are part of the Epic. But this is still a bit grey in terms of how to make your decision. The choice really comes down to personal preference and how your Jira configuration was customized. Most of the time my projects are small enough that I don’t use an Epic. However, if I’m performing a massive overhaul or I’m managing a large team I tend to use Epic’s a bit more frequently.

In this example I am going to create a Task ticket called _Monthly Revenue Dashboard_. The next question is do I need to create any subtask tickets for this unit of work? If you said no, I’d encourage you to think a little deeper about all of the touch points to this unit of work. In most cases where we’re creating dashboards we’re going to need to create the following sub-tasks:

• Monthly Revenue Dashboard: Create Tableau Dashboard
• Monthly Revenue Dashboard: Create ETL to populate database table to support Tableau Dashboard
• Monthly Revenue Dashboard: Create documentation for database table
• Monthly Revenue Dashboard: Create documentation for Tableau Dashboard
• Monthly Revenue Dashboard: Create pipeline for ETL

Each of these tickets should have someone assigned to the ticket to create accountability. There are many other fields that can be completed but again, it’s at your discretion depending on how you want to manage your projects. You can create story points, sprints, create custom tags, and more. All of these fields that you decide to use should ultimately assist with project scoping, management, and help you to quickly search for tickets in the future. But the most important part to the ticket is the subject and description.

Now that you have a brief introduction to ticket types we can discuss some of the best practices around creating tickets. When thinking about the best practices, it’s useful to think about how your ticket will stand out after thousands of tickets have been created in Jira.

Summary

The summary of the ticket should describe a single unit of work but it should be descriptive enough to allow users to quickly understand the purpose of the ticket without reading the details. Also, the subject should be descriptive enough to allow users to quickly search all of the Jira tickets based on the text of the subject in order to find the desired ticket(s).

Poor Example

Summary: Bugs in Revenue Dashboard

This is a poor example because it isn’t descriptive. Stating that there are _bugs_ is very generic. How would this ticket be any different from another ticket that will be created 2 months from now when more bugs are found? Writing with generic descriptions is going to make all of _bug_ tickets sound the same. Also, if you’re on the receiving end of this ticket and are reading it for the first time you really won’t understand the issue without digging into the details. This would be the equivalent of removing all subject lines from email messages. Suddenly you’d find yourself spending a lot more time reading emails and trying to understand what the main topic of the email was. How useful would a Google search result be if all restaurants were simply described as “restaurant to eat at” as opposed to the actual restaurant name and a summary of the type of food that they serve?

Proper Example

Summary: Monthly Revenue Dashboard: March 2019 revenue is stated at $0 for all countries

This description is pretty clear about what the problem is. It describes the specific product or domain where the problem exists. In this case it’s the Monthly Revenue Dashboard. Next, it is very clear about the perceived problem. One can probably deduce based on this ticket that the revenue should not be $0 (otherwise why would someone have entered the ticket). Also, it is very specific about where this problem occurs (in March 2019). By specifying the month, it makes it seem as if this is the only month where the problem is occuring. This gives the reader a pretty good lead into what the problem is and how widespread it is. Now the person investigating the bug will have a good idea of what to investigate based on when things were probably working and when they stopped working.

Altering the subject

Generally speaking you should avoid altering the subject of the ticket. This isn’t to say that once you create a ticket that you can never update the subject. There are many times when you may realize that you wrote a poor or misleading subject and you need to add clarity to it. Other times you may have misstated the problem. In the previous example, maybe you thought that March 2019 was the only month that had an issue. However upon deeper investigation you find out that it has been occurring within the last 3 months. This would be a valid reason to update the subject. So when shouldn’t you update the subject?

A subject shouldn’t be altered in a way that morphs the original ticket and work. For example, let’s assume that our original subject was _Monthly Revenue Dashboard: March 2019 revenue is stated as $0 for all countries_. As time progresses, investigations take place, comments are made to detail the findings, questions are asked in the ticket, and code changes are made. After all of these things have taken place you also find that there is $0 in revenue in February 2019 but only for Australia. No other countries seem to be impacted. Based on this information it would appear that these are unrelated issues. It is a bad practice to alter the subject of the ticket to now state _Monthly Revenue Dashboard: February 2019 revenue is stated as $0 for Australia_.

The reason that this is a bad practice is because you’ve just broken the ability to properly search for tickets or understand what work was performed based on the ticket summary. Worse yet is if these are two completely different issues you’ve lumped them into the same ticket. This would be the equivalent of searching for a local restaurant that serves pizza. The search results might display the name of "Rick’s Place" but when you click the link, you’re taken to a website about Rick Astley. Or maybe the search results just never display "Brandon’s Pizza" because someone changed the subject to "Brandon’s baseball cards". Either way you’re not going to get the results that you would expect.

The solution: Just create a new ticket. It doesn’t cost anything except maybe an extra 15 seconds of your life and it’s the right way to proceed. Also, if you really believe that the two tickets are related, you can always just link them to tickets in Jira. This will cause them to show up in the “related” ticket section.

One issue pre ticket

Describing multiple problems in a single ticket is something that I’ve seen happen quite a few times. The only time that I find this to be acceptable is if this is described in a User Story or in an Epic ticket because I’ll need to break out all of those individual items and place them into their own individual tickets.

What tends to happen is that someone will place a couple of requests into one ticket and I’ve mostly seen this during QA processes. For example, someone will be performing a QA check on a new feature, dataset, dashboard, or anything else that you can think of. During this process someone opens up a single Bug or Task ticket and describes a few different problems. For example, let’s assume that someone found 2 bugs during a review of my Monthly Revenue Dashboard.

Issue 1: Customer Type filter selection doesn’t cause data to change in the dashboard

Issue 2: Australia isn’t being displayed as one of the rows in the table

While both of these issues were found during a QA review, they are probably caused by two different problems and as such, they should have their own ticket. Even if they are caused by the same problem, when in doubt, just open another ticket. The reasons for creating two different tickets are the same reasons described above when it comes to altering a ticket. If you have two distinct issues and you combine them in a ticket it’s going to be hard to search for the ticket. Also, when it comes to tying code to your tickets you’re going to create another point of confusion about what was changed in the code (and why it was changed) and how this information matches to a ticket.

Linking Tickets

Tickets can be linked to one or more tickets. This is a great way to chain tickets that have any sort of relation because it allows the end-user to have a clear picture of what changed. In my original example of creating a dashboard where I had 5 sub-tasks, each of those tickets would automatically be linked to the parent or Task ticket. This can be very helpful if you want to navigate up to the parent ticket to see if there are any additional child tickets that are associated with your unit of work. Another example would be around a bug that you’ve seen before. Let’s assume that this month you are running into an ETL load issue where it didn’t seem to complete on the standard schedule. However, you recall entering a ticket for the same issue about 6 months ago. While the cause of the issue might not be the same, it could be helpful to other team members if you link the two tickets together. Again, you don’t know who might be fixing the issue and maybe the person that fixed it 6 months ago isn’t the same person that is going to fix the issue today.

Proper Details and Description

This is by far one of two areas where I see the most issues. A description is critical to the understanding of the ticket but I’ve seen so many tickets where someone just typed in a sentence or two as if everyone else (current and future) is a mind reader and knows everything that the ticket creator knows. For example, let’s assume that you found an issue "Monthly Revenue Dashboard: February 2019 revenue is stated as $0 for Australia". While this is a good subject, it would make for a poor description but yet this is fairly close to what I’ve seen for descriptions. Let’s put ourselves in the shoes of the person that has to fix this issue, the project manager, or the person that encounters the exact same problem 6 months from now when you’re not around.

A proper description should probably include, "who, what, where, when, why, how". This subject really only includes a minor amount of "what" we are seeing ($0 revenue for Australia) and a minor amount of "where" (in the Monthly Revenue Dashboard, under the Feb 2019 month for Australia). Why do I say a minor amount? Well, if you’ve never used this dashboard, how do you even know where to go look for it? Would it be best to put a link to the dashboard in the ticket or explicitly call out a database, schema, and table? When it comes to these sorts of valuable details, I’ve frequently heard the ticket creator say, “It takes too much time to enter this, it’s too much overhead, or the person should already know”. But again, many people in the future might look at this ticket and work gets reassigned all of the time so there really isn’t any guarantee that someone knows. Also, I’ve seen so many tables, databases, reports, code, etc. that are named very similar things that it is easy to get confused. Why not take the confusion out of the equation and just provide the details? A few extra minutes of work saves everyone in the long-run. Also, it makes it look like you care about the work and about others. Providing the bare minimum and making assumptions tends to make a person look lazy and not like a team player.

So what would a good ticket look like in this case? Here’s one example and we can try to template out the different areas of "who, what, where, when, why, how" that we need to explain.

• Where (was the issue found) — In the Monthly Revenue Dashboard (located at http://mydomain.tableau/monthly_revenue_dashboard) in the section for "Revenue by Country" I am seeing where the revenue numbers do not look accurate. If you filter for Country=Australia and Month=February 2019, you’ll notice that Australia’s revenue is $0.
   
• What — If we look at all other months over the last 12 months, Country=Australia has typically been around $12,000. For some reason February 2019 is reporting as $0. When checking other countries I didn’t see that any other country had a $0 value and with spot checking of a few main countries (US, UK, DE, CA), none of those countries appear to deviate from what I would normally expect to see.
   
• When — I noticed this on 3/5/2019 on the dashboard and I checked Tableau and it shows that the dashboard dataset was refreshed on 3/5/2019 01:00:00 so I think that the data in the dashboard is up-to-date with whatever is in the database table. I also checked the underlying table (on SuperTera database, p_finance_analytics.monthly_rev_rpt) that the dashboard uses and this data matches what we see in Tableau.
   
• Who — "We’ve basically already covered this because we created the ticket and we’ve said “I” plenty of times when describing what we saw and what we checked"
   
• How — "We don’t know how this is happening and what is causing the issue to happen. But we have described how we came to notice this issue"
   
• Why — "We don’t know why this is occurring but we did acknowledge that we checked a few usual suspects (the database table and the Tableau dataset that is on a refresh schedule) to provide some sort of lead into where the problem might be occurring"

This is a pretty good description for a ticket and when combined with screenshots, it makes it very easy for someone to troubleshoot. Now you don’t have to write out all of the "who, what, where, when, why, how" headings but if they help, do what works for you. Other teams will have a template that sounds a little different but it basically covers the same thing. For example, you might see (or want to use) the following template:

• Where is the problem being noticed (provide detailed tables, reports, schema, database, URL, browser etc.) where you saw the problem?
• Describe in detail what you are seeing
• Describe in detail what you would expect to see in a normal state
• What are the reproduction steps (step by steps actions taken so that someone else can get to the same state that you are in for your environment)?
• When did you first notice the problem?
• Have you seen this issue before?
• Is it intermittent?
• Do you have screenshots (preferably with annotations and arrows pointing to the problem)
  Is there anything that you did to investigate the problem (be detailed). Note things that you did not check. The idea is to ensure that as you’re describing what you did check that you are not accidentally making it sound like you did more than you did.

The above template will also suffice when filling out the details of your ticket. However, your template may differ slightly depending on the type of ticket that you are entering, the environment that you’re working in, and the products that you are working with. For example, in a QA environment where I’m entering a "bug" ticket for the development team, I’m going to provide a lot more details about the OS (Android, iOS, the version of my OS, the physical device type, and the version of the app that is on my mobile device). In an analytics environment, I’m going to provide all of the relevant information about databases, schemas, tables, views, scripts, time of script execution, and dashboards.

Be deliberate and specific

In the above example I mentioned describing what you "did" investigate and to note things that you "did not" check. This is extremely critical because if your ticket is poorly written, the person on the receiving end is going to lose trust in your work very rapidly. Here’s an example of what I mean. Let’s say that you created our same example ticket for *Monthly Revenue Dashboard: February 2019 revenue is stated as $0 for Australia*. When describing what you checked you stated that *this isn’t happening with any other country* and that you *checked the other countries*. However, in reality, you really only did a quick scan of what was on the screen and you didn’t actually analyze it in depth. You’ve just over generalized and misled the reader about what you tested. They are taking you at your literal word (because how else would they take it?) and they will be relying on your information at times as a short-cut to things that you’ve already tested and ruled out.

However, in reality because you didn’t check every country, you failed to notice that it isn’t just Australia. It’s actually every country in the APAC region. This might be valuable information for the reader when troubleshooting. It would have been better if in your description you has said exactly what you did/didn’t check such as, “This doesn’t appear to be happening to other countries based on my spot checking of US, UK, DE, CA”. See the difference?

Because so many tickets are written as over generalizations I tend to assume that someone isn’t telling me something. I learned that lesson over 20 years ago when doing computer consulting. A client would typically say, “This isn’t working on my computer or network” and I would immediately ask, “Is there anything that you changed” and the answer was always “no”. However, I quickly learned that this was almost never the case so I stopped asking this question. Someone, usually that specific client, did indeed change or do something and they cause the issue. However, it’s not that the client was being malicious; it’s just that they either forgot about the change or they really didn’t see how that could have impacted anything. Anyway, try your best to be specific, be literal, and don’t over generalize or mislead with your words.

Commenting

Commenting on tickets is another important area to cover. Just like the description, it’s important to provide proper details. Since most of this concept is covered in the previous sections and in my other article “What Jira is and how you should be using it”, I’ll just provide a few examples of how things should and shouldn’t be commented.

Let’s take our QA example where we submitted a bug ticket. The person that fixes the bug should comment back on the ticket with proper details.

Poor Example

Bug has been resolved

This example above is almost useless other than telling you that it was supposedly fixed. There is no indication of what caused the issue nor is there any indication of what the fix was. Was this caused by a system outage? How was the data restored? Did you have you run a special one-off script (which could have caused other errors) or did you have to truncate a table and re-populate all of the data (which again, could have introduced other problems), or did you fix the ETL script that could have introduced yet another bug? Also, when should I expect to see the resolution on my dashboard? I need to know this because I have stakeholders that want the information and I also need to QA the data/tables.

If these details aren’t provided, I’m going to have to go back to the developer and ask a slew of questions so that I have the right expectations and so that I can double check the results.

Proper Example

Upon investigation we noticed that the APAC database cluster

had an outage at 2019–03–02 (see Jira Ticket 5234). There is

a scheduled job that runs on 2019–03–02 01:00:00 as part of

our monthly database refresh. So when this went down the ETL

job never pulled the data from the APAC database and loaded

into our global database. I double checked with the Engineering

Opps team ([email protected]) and they assured me that

there is no data loss.

I manually triggered the ETL job and double checked the

p_finance_analytics.monthly_rev_rpt table to ensure that the

data is present. A quick spot check here makes it appear that

all of the values are in-line with historical values but you

should check as well. You might need to manually refresh your

Tableau datasource or wait for the next scheduled refresh. No

code changes were made. Closing out ticket as resolved.

This above example is a very well commented ticket. We know the source of the problem, what was done to resolve the issue, call-outs for other things that I might want to be aware of (related tickets, team member contact info, and no code changes), how this was QA’d, and what I can expect.

Here’s another example of ticket commenting. Let’s say that now it’s your turn to QA the work before telling your stakeholders that this issue has been resolved.

Poor Example

Issue resolved

Again, this comment tells us nothing about what you actually did to QA the code. Did you blindly just assume that it works because the previous person said so? Did you refresh the datasource as suggested by the previous person and double check that the data shows and that there isn’t a cache issue that still causes $0 to be displayed? A proper comment would be as follows:

Proper Example

Refreshed Tableau datasource. Checked dashboard to ensure

that $0 isn’t being displayed for all APAC countries (JP, CN,

AU, NZ). Checked the Feb 2019 values for those countries

against the values for the last 12 months. All values seem

to be as expected and are within +/- 5% month over month change.

Emailed stakeholders (actual names) to let them know that this

issue has been resolved. Closing Ticket

In the above example, we are very clear about exactly what we checked and what we saw that helps us to determine that everything is in working order. Now if anyone comes back in the future and asks what we did to test this or if we see a similar issue (let’s say that we forgot about Singapore and there’s an issue) we’ll know that we didn’t actually check that country so it could be a related issue or something completely different. But we won’t have complete confidence that the issue was resolved for Singapore under this ticket.

Frequency of Commenting

How frequently you should comment on your ticket might be somewhat debatable. However, I have general guidelines that I try to follow for myself and my teams.

Comment at least once per day (assuming you worked on the ticket during the day) — Anything less than this isn’t really helping anyone. At the end of the day you will have investigated, tested, modified code, etc. and will have some sort of status to provide an update on. If you aren’t updating a status, a new day will come tomorrow and you’ll probably have forgotten some crucial aspects. But again, remember that other people might be reading into your tickets to see how things are progressing. It’s going to look like you are doing any work if you didn’t comment. Also, there’s always a risk of getting pulled in other directions and not getting back to this ticket for a few days. By that time you’ll probably have forgotten where you left off and what you need to do next.

As a status update, I tend to be detailed about what I worked on, how far I got, and what I need to do as next steps. For example:

"Started looking into this issue. Verified that the database table does indeed have a $0 value for all of the APAC countries. I looked at the ELT script at (../..) and I didn’t see any changes to the code in Git. The pipeline job in Airflow that triggers this ETL seems to have completed as scheduled per the log files at (…). Need to dig into the source table that the ETL pulls from to see if there are any issues with that table or the jobs that populate that table."

With a message like this, I’ll know what I did and what I need to do the next time I look at this ticket.

Comment as you reach milestones in your investigation- Piggybacking off of my previous comment, let’s now assume that I made that comment at 11:00am and I’m going to continue working on this project. It feels like my previous comment would be a good milestone of what I investigated so I should just make the comment. It only takes a few minutes to make a quick update and then maybe take a break and go grab a cup of coffee. When I come back I’ll investigate the next part in the data flow.

After doing some additional investigation I come back with more details and add another comment and maybe some screenshots. While it sounds like I’m being overly detailed about what I’m doing, I don’t feel that I would use the word "overly". I’m just being detailed about my work because there’s a really good chance that I’m going to sit down with someone and ask for help or that I’ll pass this information along to another team member in the company. Having these details make communication really easy. Plus, if I’m doing daily stand-ups with my team (which everyone should be doing), you’ll have already summarized your work, making it easy for you to give a quick update on what you’ve been working on. I have found that when people don’t write good comments in their tickets that they tend to struggle to verbally summarize their work in a stand-up meeting.

Closing

I hope all of these tips help you and your team stay organized. In a future article I’ll talk more about some customizations and project management features that will help to keep individual team members as well as managers organized.