Read on Twitter
So other than following up on shit that should have been done but wasn't, sifting through miles of forwarded emails (all with full quote below a statement saying "my comments in red” or “+cindy”), and cursing Slack "threads", I spend a good chunk of my day juggling Jira tickets.
So much of our work is ticket driven, yet many of us seem to lack basic best practices and habits that could make our (ok: my) life a lot easier. So let me present a quick primer:
Essential Ticket Skills - just because Jira sucks doesn't mean you have to!
Essential Ticket Skills - just because Jira sucks doesn't mean you have to!
(Note: most of this applies equally to Bugzilla, GNATS, or whatever bugtracking software; I just happen to use Jira at the moment, so that's what my examples are based on.
And don't you fucking start with Trello or sticky notes and "swimlanes". Those can fuck right off here.)
And don't you fucking start with Trello or sticky notes and "swimlanes". Those can fuck right off here.)
How to create a useful bug report has been covered at length elsewhere. Here's a good start by @noahsussman: http://infiniteundo.com/post/36678096413/how-to-write-a-bug-report
Before filing a bug, you have to do your homework. In a nutshell:
Required:
- Description Of Problem
- Steps To Reproduce
- Expected Results
- Actual Results
Recommended:
- Screenshots / exact copy of terminal I/O (script(1))
Optional:
- Suggested Remediation
- Code Patch
Required:
- Description Of Problem
- Steps To Reproduce
- Expected Results
- Actual Results
Recommended:
- Screenshots / exact copy of terminal I/O (script(1))
Optional:
- Suggested Remediation
- Code Patch
Yes, that’s a lot of work. But just by preparing a bug report with these details, you'll often find a solution. This is a variation of Rubber Duck Debugging: https://hwrnmnbsol.livejournal.com/148664.html
But tickets are not only for bug reports and not only for software products. A lot of our tickets track operational tasks, development efforts, project management, patch management, incidents and remediation, software updates, ...
Opening those types of tickets requires the same diligence as filing a bug report. But aside from trying to address a specific issue at a specific moment in time, tickets serve another important purpose:
Tickets are a time machine, a log of activity, documentation of rationale & reason. Treat tickets as future historical artifacts to help you understand your systems then & now, as append-only logs.
(Shush you, I heard you mumble 'blockchain’. You should be ashamed of yourself.)
(Shush you, I heard you mumble 'blockchain’. You should be ashamed of yourself.)
Which gets me to some anti-patterns: Don’t edit comments or even the original description for anything other than typos that if left uncorrected would change the meaning.
Anything more than that should be appended via a new comment.
Anything more than that should be appended via a new comment.
Don't "clone" tickets, then change the description, summary, watchers, etc, then move it into a different product. I get it, you’re too lazy to copypasta, but if you need to open multiple identical/similar tickets, use the API.
98% of the time you do not want a "clone".
98% of the time you do not want a "clone".
If you have related tickets, *link them explicitly*. Mentioning a ticket in a comment is not sufficient. Links are bidirectional, comment mentions are unidirectional, cannot be easily consumed via the API.
(Adding a comment *why* the tickets are linked can be helpful, though.)
(Adding a comment *why* the tickets are linked can be helpful, though.)
If I ask you questions in a ticket, don't answer them outside of the ticket. The ticket is our log of how that issue was resolved. Keeping all the information in place means I can go back months later and figure out what was done and why.
If you have code commits that relate to a ticket, include the ticket in the commit message.
Ensure your repository automatically updates tickets based on commit message mentions.
If it doesn't, manually add a link to the commit or pull request together with the commit message.
Ensure your repository automatically updates tickets based on commit message mentions.
If it doesn't, manually add a link to the commit or pull request together with the commit message.
Code repositories get migrated. I have tickets from >10 years ago that link to CVS, which then was migrated to SVN, which then was migrated to git, and now I have no way of getting the diff.
For this reason, I like commit messages to be automatically appended to a ticket *together with the diff*: this keeps your ticket self-contained and future ticket spelunking will not require the code repository to still be available.
Btw, it's no coincidence that good commit message best practices translate easily to good ticket updates. Both are about communicating with others (including your future self). See e.g.:
https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message
https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html https://www.slideshare.net/TarinGamberini/commit-messages-goodpractices
https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message
https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html https://www.slideshare.net/TarinGamberini/commit-messages-goodpractices
Don't willy-nilly assign tickets to people.
Different teams have different processes for triaging incoming tickets. Some use ‘unassigned’ as a triage trigger, others use a mailing list, etc. Don’t break their process.
(Corollary: have a triaging strategy for your intake.)
Different teams have different processes for triaging incoming tickets. Some use ‘unassigned’ as a triage trigger, others use a mailing list, etc. Don’t break their process.
(Corollary: have a triaging strategy for your intake.)
Understand the general lifecycle of a ticket (roughly: reported/unassigned, triaged/accepted, assigned, in progress, resolved).
Example image from Bugzilla:
Example image from Bugzilla:
Refrain from passive-aggressive ticket closing, re-opening, closing, re-opening games. It really pisses people off and usually moves you further away from actual resolution.
Using labels, types, keywords, etc. to gather metrics is great, but ultimately the biggest value derives from the contents, the comments, the details in the ticket, consumed by humans.
Let others find your tickets. Let them comment. Don't restrict visibility or access!
Let others find your tickets. Let them comment. Don't restrict visibility or access!
Metrics are useful, but beware of the incentives you (may unintentionally) create. Don't measure e.g. "open tickets” or "closed tickets”. https://twitter.com/jschauma/status/623920684096471040
But most importantly: keep all information in the ticket. No emailing me answers, no slacking me updates, no stealth commits, no calling me... KEEP IT IN THE TICKET.
Thanks for indulging me in my twitter ramblings. Now back to my usual Jira routine...
