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.

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?

Possibly Related Posts:


10 Books to Push Your Thinking about Learning Design

Today I was thinking about what books I would recommend to someone in order to have some experience of the learning journey I’ve been on for the last 8 years.

If you’re looking for some summer reading that will help you grow your mind, here’s my list:

1. Theory of Fun for Game Design: This will help you to understand the principles that make games addictive learning activities and help you create more desire to learn for any audience. Really, I’m not kidding.

2. Bringing Words to Life, Second Edition: Robust Vocabulary Instruction: While this is written for teaching vocabulary to the K-6 age group, the research and activities described in the book are fascinating. The research principles and guidance on how to teach for various categories of words are sound for transfer to any age.

3. Design For How People Learn (Voices That Matter) I think this is a must read for understanding visual design principles related to learning. To be fair, I have also had the benefit of many long and interesting conversations about learning and design with Julie, so on this one, I might be biased.

4. Flow: The Psychology of Optimal Experience (Harper Perennial Modern Classics) During flow, people typically experience deep enjoyment, creativity, and a total involvement with life. We should seek to get learners into a state of flow, and then do as little as possible that disrupts them.

5. Don’t Make Me Think, Revisited: A Common Sense Approach to Web Usability (3rd Edition) (Voices That Matter) You don’t really understand usability until you’ve carefully considered how users interact with the digital interfaces they encounter. Everyone should read at least one book on usability if they are designing a digital product.

6. Cognitive Development and Learning in Instructional Contexts (3rd Edition) An amazing book about learning! James Byrnes is a top-notch explainer. It looks like it might be a textbook, but it is a fascinating and thought-provoking read. My copy has notes and highlights everywhere.

7. Understanding Learning and Teaching (Society for Research Into Higher Education S)The research group associated with Trigwell and Prosser has done some absolutely fascinating work related to motivation to learn, perceptions of the learning environment, perceptions of the discipline, and how students perceive themselves as learners. Most of the research is seated in STEM education, but anyone in education can appreciate the elegantly-designed experiments and their outcomes/implications for learning design.

8. Where Good Ideas Come From There are some great gems in this book (like the adjacent possible concept) that will help you to develop your own practice of innovation and understand that ideas are not as rare as you might think.

9. By Clay Shirky: Cognitive Surplus: Creativity and Generosity in a Connected Age which can only be read in conjunction with it’s complete opposite, The Shallows: What the Internet Is Doing to Our Brains

10. e-Learning and the Science of Instruction: Proven Guidelines for Consumers and Designers of Multimedia Learning  This is a newish version of an old standard, but I love it because every “prescription” is backed by research and conflicting studies are carefully dissected into their nuanced differences. It’s an easy read and a good “go to” book for when you need research to have your back.

Possibly Related Posts:


University of Copenhagen Keynote

Just thought I would share the recording of “Surviving (and Thriving) in the Age of Digital Enhanced Teaching”, recorded at The University of Copenhagen. It includes some research I’ve been diving into about why student engagement, particularly interactions, are so important for learning. Enjoy!

Possibly Related Posts:


What does Math Teaching look like in 2020?

This is from a presentation today looking at the future of teaching math from a K-12 perspective. Here are my predictions for math teaching at the K-12 level in 2020:

(1) Learning math becomes a team activity, where technology is one of the team members.

(2) Teachers shift from the role of an instructor to the role of a learning coach.

(3) We solve the mobile devices and assessment problem.

(4) Students can move seamlessly between in-person and digital experiences.

(5) Teacher planning periods shift from lesson planning to examining analytics and choosing digital / in-person learning activities.

 

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: