Best Practices: Thoughts on Issue Hierarchy in Jira Software

[#1]

Issue hierarchy in Jira Software is a common point of confusion for new users, whether they're novices or seasoned agile veterans. Since confident utilization of work hierarchy is key to running effective development cycles, below, I'll cover how hierarchy works in Jira Software, and what its implications are for your work.

Issue Hierarchy

Issues are the basic unit of work in Jira Software and come in various types: story, task, bug, etc. There are two additional issue types - epic and subtask - that can possess a hierarchical relationship with the aforementioned standard issue types. Let's run through some quick definitions.

1. An epic is a large work item made up of subsidiary stories. Epics will often span multiple development cycles, projects, and versions.
2. A story is a single unit of work that, taken alongside a larger group of stories, constitutes an epic. A story should be small enough that it can be completed in a single development cycle.
3. A subtask is an even more granular decomposition of the work required to complete a story.

Alternatively stated, an epic can contain stories and stories can contain subtasks. So, hierarchically, imagine the overall relationship like this.

Behaviors

So what implication does hierarchy have on how you actually do your agile work? Let's cover this in two discreet topics: estimation and time tracking.

Estimation is the practice of sizing of your work and correlates to how you calculate your team's speed of work. In Jira Software, estimation occurs at the story level, which then rolls up into its parent epic.

You do not estimate at the subtask level.

Why? For Atlassian, in a well-rounded agile practice estimation should be sufficiently accurate that overall capacity will be understood without having to parse estimations at the subtask level. Subtask estimation leads to slowdown; agile is about speeding things up.

Time tracking in Jira, on the other hand, is a burndown of hours that will allow you to monitor progress against a unit of work. Tracking will typically possess a different value than estimation, i.e. you might estimate in story points but track in hours. One thing to note: in the case of tracking, you can establish original time estimates at the subtask level, the value of which will sum up into a parent story. However, tracking values will not roll up into epics.

For clarity's sake, here is the above diagram, again, with estimation in yellow and tracking in grey.

So, when you decide upon an estimation and tracking system, consider the above behaviors. What estimation and tracking statistics will you use? Do you want to track time or will you trust that work should be complete by cycle's end? While you're free to choose your own estimation and tracking statistics, separate statistics are preferable to make sure you aren't conflating the two metrics.

Additional Considerations

1. There are no additional levels of hierarchy available in Jira Software beyond what's described above. If you're looking for a more hierarchical view, you might consider some marketplace extensions.
2. Out-of-box, the only issue types that can be estimated are stories and epics. That said, you can add the estimation field to other issue types (tasks, bugs, and any custom types).
3. For more on how tracking statistics can impact your burn down reporting, read more here. 

[Dim Menshchikov]

Hi,
if the hierarchy is such: epic - story - subtask, then why do I need tasks?

[Matthew Wong]

Hi Dim!

Good question. Tasks are on the same hierarchy level as stories in Jira. We create different "issue types" to create different categories of work. In this case, stories are meant to describe and articulate features. Tasks would, in theory, be more routine or rote work. Regardless, issue types are meant to provide flexibility in the taxonomy of your work.

[Huwen Arnone _Deiser_]

Very useful for new users! Thanks.

[Oleg Zakharov]

Thanks Matt! 

Where is a Feature fits into this JIRA model?   

[Subhra]

Hi Matthew,

As per the hierarchy provided by you, if i am creating an issue under sub task 1, then why i have to link it manually to the epic?In Scrum board if i group by epic , it is showing issues without epic.

One more question, if i am marking an issue as issue that Blocks a Sub-Task , then when we group by sub task, why the issues is appearing as not linked to any sub task?

[Ondřej Wretzl]

Hi I miss a Feature level in JIRA model.
Work with sub-tasks is hell.
It is normal to use bigger work packages like Features in roadmapa and I miss it.
Please learn hierarchy from Target Process.

[Alexander Bondarev]

@Matthew Wong , great article, thanks! 😊 

[ISAAC SANUSI]

Wow! this is really helpful. Thanks 

[jbedar]

Related question (IMO) - if Atlassian defines an initiative as a program (collection of related projects - e.g. Engineering), I'm not understanding why they don't have it available OOTB in terms of hierarchy.  Granted I'm trying to use Jira as a 'legit PM tool', which it isn't, but seems like there would be an easier way to implement this.  "Plans" (Adv Roadmap?) is still kinda discombobulated in terms of putting it together and creating a dashboard view in a similar format.  Just looking for some guidance on the best resources to learn the 'best practices' to configure these tools.  And yeah, why they don't use tasks under story with sub-tasks under that also puzzles me - just logically :).

[antoine_viau]

This intro says it all...

Issue hierarchy in Jira Software is a common point of confusion for new users, whether they're novices or seasoned agile veterans. That's pretty much everyone!

Then why don't you address the issue properly by giving the users a project preference feature that would let them place tasks as a sub level of a story and preserve the subtask management for the team members as a to do list.

[jbedar]

@antoine_viau Novel concept. This tool gets more and more frustrating by the day :). 

At this point, it is seemingly easier to work with an actual project (unique, end date, etc.) than the 'jira project' which I had to use a software project, strip the agile / sprint related elements because it seems to be the easiest way to formulate some type of project hierarchy (non-sprint based efforts).  For now, I am using Epics as 'projects' since the majority of what is in our Jira (probably most orgs using it) are NOT projects.  Enlisting Tasks as effectively 'work packages' and sub-tasks are the 'steps' to complete the work package.  For me it is the only way it makes sense in an org that is split between sprint based development (where Jira makes more sense) and related / dependency based efforts.  Not sure why Atlassian cannot pick up on the fact that in North America and Europe (PMI, OGC, PRINCE2) all follow a similarly defined views of projects and programs.

According to the PMBOK® Guide— the definition of a project is “a temporary endeavor undertaken to create a unique project service or result.” Projects are temporary and close down on the completion of the work they were chartered to deliver. Obviously this doesn't really apply across the agile / scrum methodology, but if you are going build a tool that masks itself as a project management tool (although all I hear is ticket tracking tool), why not follow the general definition of a project? or program?  Jira's 'mis-use' or decision to 're-purpose' project management terms is a big part of why this is confusing (IMO) and should be adjusted across the solution.  For Jira, this is what I see as the issue...

• "Project" = Program (group of related projects) or what they call Initiative, which is not readily configured OOTB for hierarchy
• "Epic" is a project, Story is really equal to an Epic or provides a way to divide the project into phases; No way Story should be equal to Task - just not logical...a list of tasks would be derived to complete the effort needed to achieve the functionality described in a Story
• Sub-task is misleading and really unnecessary (unless something like a blocker).  If a Task needs to be broken down into sub-tasks, then it isn't just a task

The definition of a program “a group of related projects managed in a coordinated way to obtain benefits and control not available from managing them individually. Programs may contain elements of work outside of the scope of the discrete projects in the program.”

Aside from that, I'd love to feel like I can actually get guidance / documentation from Atlassian in terms of best practices.  This community feels like when I learned SharePoint 2007 - trial and error to see what might work. Sorry for the vent...just annoying the level of modification required to for things to make sense vs. fluid functionality (e.g. can only create multiple boards in a software project (again attempting to separate related projects within a Jira "project", unable to maintain the visibility / communication lines when moving tickets between 'projects' unless in a service desk format...) All these templates but event the PM template is lacking this type of structure.  Guess maybe I expected too much from the tool. If my org would let me, I'd be using Microsoft Teams w/ Planner / to-do or even Excel :o!

[Lars Fessler]

@Matthew Wong 

Hi Matthew,

thank you very much! This really helped me understand Jira hierarchy!

Best Regards,

Lars

[Rohan Mahalekam]

What about using one additional issue type above Epic ? I know JIRA has something called Initiative.

[Caleb D]

I still miss Team Foundation work item tracking.  Our company switched to Jira years ago and we keep bumping into the rough edges of Jira.

Feature level is one of the missed pieces.  Ability to view the backlog as a hierarchy from feature level down to subtask level is also missed.  Ability to define a Bug or Story template with pre-filled fields is missed.

[Hai Ha]

Hi @mat thanks so much for this article. 

Do we have any higher level type than Epics please?

I've seen also another types such as: Initiative, Portfolio Epic, New Features, etc.. , are those out of the box types or customized ones please? So far we use "New features" as parent of "Epics", "Portfolio Epic" is parent of "New Features", and "Initiative" is parent of "Portfolio Epic", though I am not quite sure if its the best way to use it to be honest.

Much appreciate if you could share any thoughts on this issue hirerchy, any best practices out there we're missing pls? 

Thanks so much in advance.