10 Tips for Writing a Good Bug Ticket

I have spent a great deal of time in the last two years writing software tickets for new features and bugging issues that (inevitably) arise. Many of the engineers tell me that my tickets are very clear and easy to understand. I like my engineers (I even baked bug cookies for one who visited me in Utah) so I thought I would pass along my tips to be used by more people.

bug picture

Tips for writing a good bug ticket:

1. Find a way to reproduce the bug. If you can’t reproduce it, the engineer isn’t likely to be able to do it either.

2. Write numbered steps for reproducing the bug and/or make a video showing how to reproduce. Poke at the edges to try to get the bug down to the minimum possible way to reproduce. If you have to write 8 steps to reproduce the bug, see if you really need all 8 steps. For example, maybe reproducing only takes the last three steps – if so, simplify the ticket.

There are many free apps that let you make a screencapture video and share them with a link. I use SnagIt + Screencast. Just find the right one for you.

3. If the bug involves anything visual, include a screenshot. If possible, directly include the image in the bug (rather than a link to the screenshot). It is faster if everyone that has to view the ticket can just SEE the image directly.

4. Try to include some way to test the fix in the wild, like a URL to an example of where the bug is occurring.

5. Avoid words like “it” and “that”… be clear what you are referring to.

No: When it does that…
Yes: When the mouse stops working …
Yes: When the Submit button is pressed and the feedback screen appears …

6. Avoid words like “they”, them”, and “their” … be clear who you are referring to.

No: When they press it, that turns black and their cursor disappears.
Yes: When the user presses the OK button, the dialog box turns black and the cursor in the dialog box disappears.

7. Use the same language as the platform. If “score” is used in the platform, do not use “grade” on the ticket. The engineer who works on your ticket may be seeing the feature for the first time or be unfamiliar with the alternate terminology.

8. If your engineers are foreign, be particularly mindful to use plain english in your tickets. Tickets with complicated wording may get run through a language translator and simple English will translate best.

9. As soon as a sentence starts to read like an if-then-else statment, it is probably best to just rewrite using if-then-else language. When you rewrite, do so with the simplest if-then-else conditions possible.

No: When you are adding a new image and you give it a name, sometimes the name is already in use. We should make it so that you are warned if the name is already in use, and then you can decide whether or not to keep the name.

Yes: If the name for a new image is already in use in the database, then warn the author and have them decide [Use existing] or [Rename].

10. If you are bugging something for a software system that is not your product, you should also include additional information about the computer system or digital product where the bug was detected. In particular, share the type of computer/device, the operating system and version, the browser and version.

My system is a Macbook Pro running OS X Yosemite 10.10.4, I am using Chrome Version 43.0.2357.132 (64-bit).

If you want to save yourself some trouble with back and forth questions with the engineer, do the following tests and include the results on the ticket:

Did it work in another browser?
Did it work after you quit and restarted the browser?
Did it work after you cleared the cache?

Possibly Related Posts:

The Watch: Killer Feature of the FitBit Force

I recently lost my FitBit Force in a Canyoneering mishap (Joel did say “Are you sure you want to bring your FitBit into the canyon?”) and now I’ve been downgraded to a FitBit Flex.

After many years of not wearing a watch, I’m finding myself yearning for my Fitbit Force and it’s “killer” feature: the watch.

I grew up with a watch. I taught the first few years with a watch. But somewhere along the way, the phone in my pocket and the ever-present time in the upper right-hand corner of my computer screen replaced the need for a watch. Or so I thought …

Since my loss of the Fitbit Force (which would helpfully provide the time if you tapped it), I have found myself missing a watch:

  • in the mornings, when I am too blind to see what time it is on the clock across the room
  • at dinner with others, when it is too rude to pull out a phone just to look at the time
  • on a run or walk with the dogs, when it was easy to check my wrist, but too difficult to unpack the phone from a waistband

I found myself regularly checking my Force in airports, but it was relatively useless when traveling (too difficult to change the time).  I hope that when Fitbit brings the Force back, it is able to reset its time by syncing to the time on the phone it is paired with. That would make it even more awesome.

Of course, you might tell me to just wear a watch, but I’m already wearing a Flex and don’t want to be one of those dorks wearing what appears to be two watches (though I predict this fashion coming back as we all try to make sense of the different feature incompatibilities of various wearable technologies).

When I was a college instructor, my reliable black & white laser printer was one of my most well-used technologies. Now it just sits and collects dust (along with my CD and DVD collections). While the world does seem to be moving away from “things” and towards online services in many industries (music, journalism, movies, education), there are places where the technology pendulum seems to be swinging back to practical things (like the watch).

I wonder if we’ll find the same thing happens in education? Right now online education has been “discovered” by the elite universities and is all the rage (ahem, MOOCs). Maybe in 5 years, small in-person class sizes will be back in vogue.

Isn’t it funny how the perceived usefulness of different technologies changes over time?

Possibly Related Posts:

Navigating Twitter Tutorial: The Basics

This is a short 6-min tutorial to help new and existing Twitter users learn a bit more about navigating in the Twitter web application. Do you know where to find the code to embed a tweet? How about where to make a new list or follow a list? How do you view a tweetstream as a conversation? What’s the difference between a mention and a reply?  Who can see a mention? Who can see a reply? Learn it here.

Possibly Related Posts:

LinkedIn Connection Timeline

Just a little demo of what the LinkedIn Lab Connection Timeline shows you. A visual representation of who your connections are from different phases in your life.

Here’s How:

  1. Go to LinkedIn Labs Connection Timeline.
  2. Follow the directions to sign in to your LinkedIn account and share your data.
  3. Wait.


Possibly Related Posts:

WolframAlpha Facebook Report

This is a delightful exercise that everyone seems to love. WolframAlpha will provide you with an extremely detailed analysis of your own Facebook data including visualizations, world clouds, graphs, and more.

Graph of Facebook Activity over time




Here’s how:

  1. Go to WolframAlpha.com.
  2. Type “Facebook Report” and execute the search.
  3. Allow WolframAlpha to have access to your Facebook account by clicking on “Analyze my Facebook Data” and following the directions.
  4. Wait while the data is analyzed.

Note: Sometimes the report seems to stall after 100% of the data is analyzed. If this happens, simply repeat steps 1-3. The second time, the report seems to load just fine.


Possibly Related Posts: