Jira is a very powerful tool but can be cumbersome to configure at first. In this article, I propose a simple way to set up the basic functionalities of the Project management tool so that you can get relevant data from Athenian to ease product development.
1. Map pull requests with the corresponding tickets.
First of all, what makes Athenian really powerful relies on its ability to leverage Jira metadata to tell you about your code. To let us know which pull request corresponds to which ticket and enable such in-depth insights, the engineering team can tag the ticket ID (e.g. DEV-1848) in the PR title or description.
Then Athenian can map your tickets to the corresponding pull requests and tells you the percentage of PRs we are able to associate to Jira issues. This mapping is interesting for 2 main reasons. First, pull requests stand for the best indicators to quantify the complexity and engineering effort behind Jira issues (story points are an attempt to do so but are hard to evaluate and remain an artificial metric). Second, this mapping allows Athenian to extrapolate all code metrics to Jira components, eg.
Lines of code added per epic.
PR Cycle Time for high priority bugs.
Average code review depth for tech debt issues.
Average PR size of customer-facing bugs.
2. Group features into epics.
According to Jira, epics are large bodies of work that can be broken down into smaller tasks. At Athenian, we like to use epics as MVPs of features so that it stays time-bounded. Constantly adding minor enhancements and low priority bugs to one epic makes it last forever and unnecessarily delays the feedback loop.
Assigning somebody an epic is also a good way to make a person accountable for the end-to-end delivery of the feature. Otherwise, engineers might be missing the big picture if they are only responsible for their tasks related to a subset of the context.
Since Athenian maps Jira tickets and pull requests, grouping the work into epics allows to break down engineering metrics by feature:
How many pull requests and lines of code were necessary to ship a feature?
How the knowledge of a feature is distributed across your engineering team?
How much of your engineer's time have you spent on a feature?
What is the average Cycle Time of the pull requests constituting a feature?
What is the code quality behind a feature? Inferred with PR size, code review coverage, ... etc.
3. Define relevant ticket types.
In general, Jira projects have the following ticket types by default, grouped by level:
Epics
Task, Story, Bug
Sub-task
In practice, Bug tickets are used properly since it is explicit, however people tend to group randomly all other kinds of work under Task or Story tickets. Adding other ticket types in your Jira instance is a good practice to get the most representative picture of your engineering activity. In particular, we recommend adding the following ticket types:
Tech debt: rework caused by choosing an easy and limited short-term solution.
Design doc: used for studying and exploring a topic required to develop a feature.
In general, we encourage organizations to define story-level Jira issue types that cover all types of work your engineering team can do and that do not intersect within each other. Other examples we've seen across different organizations are: Research, Incident, Documentation, Initiative, IT Help, Question, Customer Assistance, Guidelines, Feature Idea, Compliance, ... etc.
4. Don't mix concepts in labels.
Everybody uses labels in Jira tickets but the functionality often turns to be a catch-all category. At Athenian, we recommend using labels for one topic only. For instance, to classify tickets between themes (performance, security, usability, reliability), origins (sentry, jira_escalated, canny_request), or even complexity (first-issue, expert). The or being exclusive here: the moment we mix concepts in labels, the functionality loses its strength in terms of data we can extract from.
People tend to put everything as a label. Here are some examples of misuses that stand for other Jira fields or functionalities:
webapp, API, or infrastructure are not labels but Components.
blocked, under-review or QA are not labels but Statuses belonging to specific Jira workflows
tech-debt, discussion, or customer-support sounds more like ticket types.
At Athenian, we decided to use labels for themes which makes the engineering insights of the dedicated Athenian section very useful for product plannings and retrospectives. Indeed, it makes product objectives measurable, which is clearer for engineering who become accountable for those. Some examples of how we use it internally:
"Product performance is currently an issue. Let's improve loading times x2 without spending more than 20% of engineering effort."
"We are running an audit this quarter and expect security to represent more than 30% of our focus."
"Metrics accuracy became a major concern lately, we want to dedicate more time to fix it than adding new features."
5. Keep the priority classification and assignment straightforward for everybody.
What is important about issue priorities is to have the right number of choices. The naming or icons do not matter much as we fetch those directly from your instance. Jira offers 5 priorities by default: Highest, High, Medium, Low, and Lowest. 5 is a good number as it makes it straightforward to assign an issue its priority while remaining relatively fine-grained.
However, sometimes assigning the right priority to a ticket is not trivial or can be the role of somebody else than the reporter. That's why it is a good practice to define an additional priority level called None or Unprioritized for instance and make it the default choice. Otherwise, engineers tend to assign all tickets a random priority or worse to not raise tickets, in particular bugs, by fear of not prioritizing correctly.
In Athenian, you'll then find metrics such as Mean Time To Restore bugs depending on the priority levels you defined.
Conclusion
This post does not pretend to own the absolute Jira knowledge. It lists a couple of tips to set up your instance rightfully so that it provides you the data you need for better engineering management and product development.