Atlassian Jira

Jira tracks issues and projects.

Writing a good issue

Set an issue type

  • Story — new feature (most common)
  • Bug — fix an issue with an existing feature
  • Epic — collection of related stories
  • Task — sub-feature of a “story” (used rarely)

Write a simple title

  • Fewer words are better. Add details in the task description.
  • Use sentence casing (capitalize the first word and proper nouns only).
  • Begin with “Add/Update/Change xyz” for stories.
  • Begin with “Fix xyz” for bugs.
  • Refer to features/modules in quotes for clarity (ex: Change permissions in “manage users”).

Write a detailed description

  • Use the typography tools in Jira for readability (headings, lists, dividers).
  • Edit the description freely. Pull important info out of comments, so it’s accurate and readable for anyone who needs a recap.

Add the following sections:

  • Background — describe background info needed to assess the task
  • Goal / Problem — describe the ideal outcome, requirements, specifictions
  • Steps To Reproduce — include all necessary detail to repeat the case
  • Questions — clarify what you don’t know
  • Proposal — the potential solution
  • Reference — additional info or links

Template for description:

h1. Background


h1. Goal


h1. Problem


h1. Steps To Reproduce

# x
# x
# x

h1. Questions


h1. Proposal


h1. Reference


Set the priority

If unknown, leave blank.

Link existing issues

Use the correct relationship to specify what the link is.

Assign the task

  • To yourself
  • To someone else — “watch” the task if you want updates.

Set the epic

Pick the best fit.

Set the sprint

  • Leave blank for the backlog.
  • Or choose the current sprint.

Setup issue filters

Create two filters for each project to track tasks you’re actively and passively involved with.

GravDept: Project Name: Open

Track tasks assigned to you and unresolved:

assignee = currentUser() AND resolution = Unresolved AND project = "Something" ORDER BY id ASC

GravDept: Project Name: Watching

Track tasks not assigned to you and unresolved, but that you’re watching:

(assignee != currentUser() OR assignee is empty) AND watcher = currentUser() AND resolution = Unresolved AND project = "Something" ORDER BY id ASC


Setup dashboards

Dashboards give an overview of everything important to you. I suggest setting up a default dashboard, and a custom dashboard for each project.


Add these gadgets:

  • Projects
  • Activity Stream

Project: Project Name

Add these gadgets:

  • Filter Results (GravDept: Project Name: Open)
  • Filter Results (GravDept: Project Name: Watching)

Note: Jira is stupid because gadget search doesn’t work. Click “Load all gadgets” first, then search for the “Filter Results” gadget.