[Note: Before we dive in, you may want to take a moment light up a bowl of your favorite herbs. If you need any supplies check out Destination Smoke, the leading online headshop.]
It’s always the simple, basic things we take for granted. Things like assuming someone knows not just to clear their cache, but knows how to. Things like people understanding the default colour for a visited link is purple, that browser chrome takes up resolution size or that comic sans is meant for 5 year old party invites and bad photoshop thought bubbles.
Our industry makes it a bit different for what we take for granted – we assume the idea of source control isn’t foreign, that we know to google before asking, that making the logo bigger isn’t going to make it a better product but that it will appease the client. Mostly, though, we assume that members on our team know how to log a bug and how to log one effectively. And sadly, this isn’t the case.
This is not a scenario of ” the developer knows best” – developers can be just as fabulously craptastic at logging bugs as anyone else – which makes it worse, because they should know better. Shame on you developers. But nothing is more annoying, except for receiving emails permanently marked urgent, than seeing a bug report that is as vague as Kim Kardashian’s magnificent ass is wide.
First – not the bug, but how do we go about reporting it? Some people like to send a little email. Those are the people who promptly get punched in the throat repeatedly until they shit out their own voice box. Email is useless – it will get lost in the shuffle, there is no real way to prioritize it, there is no real effective way to see the overall state of the project based on bugs logged/resolved. Then there are those spreadsheet loving freaks who seek out any opportunity to open their very beloved spreadsheet application. So suddenly you get this document, yet another document, that needs to be updated and maintained and has it locked down if someone else is viewing it and immediately you are spending more time formatting that cell in a spreadsheet than you are resolving bugs.
And then we come to basic bug software – at this point we have lost all interest from any of the more visual oriented people, because let’s face it, generally, and I am comfortable making this generalization – bug tracking software is downright fugly. Bugzilla? Complete butterface. Adminitrack? Barf. Mantis? Meh. JIRA? Yawn. And there really isn’t any need for them to be. But if it looks good, a designer is more likely to want to use it and if it looks good and works well, its easier to other non-technical people on board.. So if bug tracking is the Mark E Smith of your software toolkit visually, you have to focus on the benefits it provides to get people committed and invested in using it.
Bug reporting is a way of communicating. Its no different than trying to give directions to your new matchstick home in suburbia hell where the urban planning looks like some city planners speed induced tribute to Jackson Pollack. You have to be explicit. You have to provide steps. You have to provide circumstances. You need to make sure that the person can get to the same destination you do if you follow the same steps. You need to provide the address. You need to provide any other items that may help them – landmarks, pictures, maps, a phone number. So here are some suggestions on how to log bugs, well maybe better?
Check before you log
Before you log a bug, do everyone a favour and search to make sure it doesn’t exist. There is nothing more annoying that duplicate bugs simply because they are unnecessary.
Bug By Bug
When logging a bug, remember you are logging a single bug. Do not put multiple bugs in a single report. One report per bug – this makes bugs easier to search, re-open and gives a better sense of activity. Some bug bases can generate release notes from logged bugs, so its important to separate items. Don’t be a lazy ass, take the time to make the multiple entries – your developers will thank you.
Before you log:
Make sure you have a way to communicate what are looking at. This is most often communicated through the idea of a build/release version. How can you be sure you are looking at the most up to date build? And moreover, how can you communicate this to other people? In terms of Flash/Flex development – a build number ( however you want to define that- a svn revision number, a build process number etc ) can be exposed to the end user in a non-intrusive way by making it available in right click context menu. This is an idea given to me by Julian Dolce, and its been one the of best, yet simple, things that I have integrated. I can always make sure people are talking about the exact same thing through a version/build number. Now its one thing to expose it and its another to make sure those logging bugs use it. You can expose to the user all sorts of things, but its important for those who log bugs to understand that its important to log OS, browser, and plugin ( including minor) or runtime versions. Educate them on what to enter , how to get those values.
Oh shit, you think you found a bug.
Try to recreate the steps you took to make the bug happen. Consider what happened versus what you expected to happen. Does this constitute a bug or a feature? Can you recreate this bug through by introducing variations into your steps to replicate? Can you always replicate the issue or is it hard to reproduce? Can the issue be replicated in other environments ( other browsers etc ) Remember, you are going to have to give directions to someone, they should be able to know exactly what to do and understand what will happen as a result of those steps.
Logging a bug
All bugs have titles of some sort. Make your title be concise yet capture the essence of the bug in as few words as properly. Think about others who might do a search in the bug base – what keywords might they use to log the same or similar bug? Vague titles help no one – “Saving File in Asset Explorer” says nothing. “Saving File from Asset Explorer saves file with incorrect name” says way more.
Descriptions should give a good overview of the bug and kinda allows you to add any other helpful information – what the issue is, expected versus actual results/outcomes, any known software or hardware dependancies etc. Most bugbases let you enter in things like OS, Browser etc. Force people to use it.
Step to reproduce
Its important to include the steps to reproduce the bugs. Write these as steps and don’t leave out a single step no matter how simple it may seem. You need to be able to provide a path for another person to take, so be explicit and write out the steps as short and concise directions.Someone who isn’t’ overly familiar with the project/feature should be able to follow the steps and replicate the bug. Start your steps from the beginning – don’t assume the user has made its way to a section/area to where the problem lies.
Record what the results where. What happened. What did you expect to happen and why did you expect that to happen.
Sometimes its hard to articulate the issue – sometimes only a picture will do. Take a screenshot and then mark up the screen shot.If you can , mark up the image, circling what the issue is or making it blatantly obvious what the issue is. This is important for things that can be design oriented – sometimes different people have varying attention to detail – so what might be a pixel off to you, someone else might not immediately notice. Although an image can say a lot, it can’t say everything. Images are not meant to replace anything in bug reporting, they are meant to help describe the problem, just visually.
If you are developer and are logging a bug against a code base or public api – provide a self contained piece of code that can be run independently that illustrates the issue. Remove your dependencies, try to replicate the bug outside of your current implementation – you’ve done everyone a favour as you’ve pinpointed the source of the problem and reduced the scope of the issue. If you point someone to your code base and implementation you are basically asking them to debug your code and theirs. Make it about them, as much as possible. Oh love, its not me, it really really is you.
Finally, be professional. Yes go ahead and laugh at the irony of that statement. Know who will be looking at your bug base. Not all clients are going to want to see your critical bug list including one titled ” Beer supplies low, must replenish for optimal productivity” when they are checking on the status of their project. Trust me.