Ever found something broken on a website and wondered how to let them know what happened? Time to write a bug report. Today we chatted with Amar Shah, our back-end developer, about what makes a good bug report.
SP: So, first off, when does it make sense to send a bug report?

AS: Any time something doesn’t work the way you expected it to, we’d like to hear about it. Not everything is a bug–it could be that something just doesn’t work the way you expected it to. But even if it doesn’t end up being a bug, it does mean that we need to clarify our explanations for what to expect from our software! And if it does end up being a bug, that’s incredibly helpful for us because bug reports are what help us build better software. We can’t catch every little glitch, and it’s good to have the customer in our corner, keeping an eye out.

SP: So what’s a good bug report?

AS: Explain exactly how you were using the software when you noticed the bug. Write out the steps it takes to reproduce the bug. Tell us about your system, like what kind of computer and browser you’re using. Keep it detailed, but stick to the facts. Include snapshots, but make sure they completely illustrate what you saw. Something that our customers might not know is that I file bug reports too. At work.

SP: How do you write a bug report?

AS: Here are the steps I follow when I write a bug report:

• I make sure to specify all of the relevant information that I could think of, and structure it in a way that is easy to follow.
• I summarize what I was trying to do when the problem occurred.
• I note any instances when we had a similar problem, and how we resolved it.
• I include the error output, if there is one.

Also, I sometimes will straight up tell them, essentially, that I’m trying my best but I don’t know exactly what I’m doing. I want to make it clear that the problem isn’t necessarily their fault, but even so I would greatly appreciate their help.

SP: What would a sample bug report look like?

AS: Well, here’s an example of a good bug report that we just made up. Intercom has always worked wonderfully for us–but here’s a report that we might send if a bug prevented setting a message end date:

Hi there,

When using Intercom today, I noticed that I wasn’t able to set an end date for my message. I’m using Chrome on a Mac OS X, and I replicated the problem on Firefox. The box to set an end date still appears, but the button appears greyed out. This happened as I was creating a new auto-message this morning. All of the other parts of the message were filled out. I’ve included a screen shot below.

Thanks so much for your help, and let me know if there’s any other information I can provide.

So it doesn’t have to be too long or complex. It just needs to explain the problem, tell when it happened, and show with examples–could be a link, could be a screenshot, whatever gets the message across as clearly as possible.

Now you can feel fully prepared to send a killer report in the event that you do come across a bug!

Amar Shah is ShareProgress’ platform developer. He lives and works in Louisville, Kentucky.