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.

Example:
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?