Pro Tip: Report Issues
Tags: developer, jira, career, tips
Published: 2022-09-14 07:08:46

---
title: Pro Tip: Report Issues
published: true
description: As an engineer, you're often the best person to report an issue.
tags: developer, jira, career, tips
cover_image: https://www.dropbox.com/s/w4jhropwh8y0knh/pro-tip-01-report-issues-1.jpg?dl=1
series: Pro Tips
---

When I’m working in teams, a frequent compliment I get from project managers is something like the following:

> It's so great that you open issues on Jira when you find work that needs to be done.

I really appreciate it, but I also consider that it’s my job as a senior developer to report issues.

And by report, I don’t mean:

- Shooting a DM to the product owner
- Mentioning it in standup
- Telling a colleague

These are things you do *after* you’ve reported the issue.

Reporting an issue means opening your project management tool and submitting a new ticket.

---

> **Note**
>
> If you fall into the camp that thinks that engineers shouldn't be responsible for writing tickets, either stop that or stop reading this article! You'll get nothing out of this.
>
> For the rest of you, don't think that I'm saying you should be a ticket writing machine. It's just that some cases, engineers are the best people to report an issue.

---

### What to include in an issue report

When reporting an issue, you should at least aspire to provide some, if not all of the following information. For now, just assume we're submitting a bug report.



#### Summary  

A one liner summarising the problem.



#### Related Items

This can be anything relevant to the issue, providing addition that provides additional context to the issue:

* Related issues
* Internal documentation
* External documentation
* Correspondence
* Etc...

Context just makes life easier.



#### Investigation  

Comprehensive details of investigation conducted and any information it generated.

#### Solution 

A precise solution, if applicable, a range of possible solutions, or advice / suspicions.

#### 

#### Estimation  

If applicable, provide a formal estimate with the given process.

---

### An example report

This *might* be a good example of a bug report. 

#### Summary 

Nav menu should collapse when it loses focus

#### Related Items

* Discovered while testing `ACME-123`
* Blocks `ACME-456`

#### Investigation  

While working on `ACME-123` I found that the when the navigation menu is not working as expected.

* **Expected:** When I move my mouse out of the menu, it should lose focus and collapse.
* **Actual:** When I move my mouse out of the menu it stays open, and only closes if I make a selection from the menu.

#### Logs

Looking in the browser console, I can see the following error:`TypeError: undefined is not a function  //...`

#### Solution  

I'm not sure what's causing the issue. But I see the above error every time I move my mouse out of the menu area, so I suspect resolving this error fixes the problem.

---

### Tell all your friends

After you've submitted your bug report, *now* it's time to do one of the following:

- Shoot a DM to the product owner
- Mention it in standup
- Tell a colleague

Oh, and make sure to include a link to the ticket.

---

### To report or not to report

Just because you can, it doesn't mean you should. 

Some examples of issues you should consider reporting:

- **It's not directly related to your current work**
  If it's related to your current tasks, just fix it. 
  Otherwise, add a report so that it can be actioned later.

  


- **It affects production systems reliability**
  In this case, you should outline what its effect is so that it can be assessed and prioritised accordingly.




- **It will change the current system operations**
  In this case, outline what the change would be and why it needs to be made.




Some examples of issues you might consider not reporting:

- **It won’t have any perceivable change to the system**
  It's very difficult to make a case for something that won't make any difference to the existing business operations. 

  


- **It’s only relevant to developers**
  Work that only effects developers almost always sinks to the bottom of the pile. If you want this work to progress, you need to be sneaky.

  


- **Reporting it would take longer than fixing it**
  In this case, it's quicker to include the change with an existing task and make a note of it for testers to check.