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.
Top comments (0)