"It doesn't work!" (aka better bug reports)

Have you ever had a bug report that just reads "It doesn't work"? Or more likely it has a bit more information than that, but clearly not enough for you to actually do something about it. You then ask for more information, and get a little bit more back - but you have to keep on emailing back and forth and explicitly asking questions to squeeze out all the information you need to reproduce, diagnose, and hopefully fix the issue.

It's really frustrating isn't it? A complete waste of time where the problem would have been resolved so much faster if the reporter had just taken a minute or two to stop and think about all the information you might actually need - including screenshots where relevant.

This not only applies to bugs, but also feature requests as well.

The thing is, in my experience, it's actually much more common than not for issue reports to have nowhere near enough information in them. It's very rare that I've had a bug report or feature request where I haven't had to go back and ask for more information. Which is kinda sad :(

Sometimes the other person might even have done some investigation of their own, but then don't mention this and their findings in the bug report! By not including details of this investigation in their report, this suggests that they're expecting you to repeat the investigations they've already done!

Quite often, this lack of detail is because the reporter is busy, and they're in a hurry to rush something out, because their time is obviously valuable. But does that imply they think your time isn't?! Of course not - in most cases, they haven't even considered and fully understood the time wastage. When it comes down to it, it's also going to waste their time as the emails start going back and forth.

Okay, so this post has been quite negative so far. Let's turn this around now, and this time, it's you who is the reporter! You've found a bug in some open source software that you use heavily. It's a hard to reproduce bug, but it's happening often enough that it's an annoyance to you when using it. The software is free, and the author works on it in her own space time. She has a full-time job and a family, and writes open-source software because she loves coding. She doesn't have a lot of time to spare though. Let's assume you're not a coder who can go in and fix it yourself, so you need to report this bug as a GitHub issue. How can you get as much information as possible into that very first issue description - so the first time the author sees the bug report, she has all the information she needs?

The first thing to do is try and picture it from their perspective. Write your bug report as you normally would, then stop, read what you've just written, then ask yourself if you didn't currently know anything about this issue - is that enough information? Can you add any more information that might both save them time and stop them having to reply back asking questions?

Could something as simple as pasting a URL into the bug report save the developer some time? How about a screenshot that will take you mere seconds to create? As they say, a picture says a thousand words. Using screen-capture tools like Greenshot (my personal favourite), or even the built in Windows Snipping Tool, makes this really easy, and also really easy to quickly add annotations to the screenshot (eg. text, arrows, etc). And if you can't make the bug report clear in text and screenshots - how about videos? Using tools like ScreenToGif makes it easy to create animated gifs so you can actually demonstrate the issue as it happens. If that's too technical for you - just create a video of your screen from your phone. If a picture says a thousand words - what does a video say?!

Take a very simple example ... In TweetDeck, I like to clear my notifications once I've read them. Unfortunately, you have to expand a panel to access the 'Clear' button. Quickly creating a screenshot like this ...

Saying something like ...

"Currently, if the user wants to clear a column in TweetDeck, before they can click the 'Clear' button (#1 in the screenshot), they also have to expand the panel (with button #2) each time. Is it possible to also have a 'clear' button at position #3 in the screenshot? This would mean that the user doesn't need to expand this panel just to clear the column."

And how about also including an animated gif create with the ScreenToGif tool mentioned above? ...

This is obviously a very simple example that could have been explained easily in just text. Infact, the TweetDeck issue isn't actually that big an issue - I just don't have a better example of a bug report that I can share at the time of writing. But it does demonstrate how screenshots with annotations and animated gifs can really help explain a problem.

So to summarise, here are a few points to bear in mind when writing your bug reports ...

• Pretend you're the other person with no knowledge of the issue. Think about whether what you've written is enough for them to continue without having to come back to you asking more questions.
• Don't delay the inevitable, and waste both yours and their time by not including as much information as possible, assuming they'll get back to ask for more information (information you could have given them in the first place!).
• Are there any URLs you could include in the bug report to save the other person having to find them?
• Have you done any investigations yourself? If so, make sure you state this, and include your findings, and everything you've tried so far.
• Would screenshots help? If so, can you improve those screenshots further with annotations? They only take seconds to create.
• Is it worth recording a quick animated gif too?

I've written this post to try and make the readers think twice about the level of details the next time they're submitting a bug report or feature request. Please help spread the word by sharing this post, and helping more people grok how how much of a time waste this actually is. It's a much bigger problem than people appreciate!

If you enjoyed this post, please help me share it by retweeting it to your followers ...

Blogged: "It doesn't work!" (aka better bug reports) https://t.co/ZBqTrjqhO8

— Dan Clarke (@dracan) September 29, 2018