No matter how perfectly architected or built, every running program or live website will eventually encounter a situation that it does not have an appropriate response prepared for. Whenever this unexpected thing occurs, the software running a website has a limited number of options.
- Fail Silently
- Fail and report the failure to a human (while hopefully logging the error).
- DO SOMETHING TOTALLY CRAZY
Each of these actions are ultimately the intended action as far as our software is concerned. At a core level, software doesn’t understand the difference between successfully logging you in to your email, deleting all the photos on your hard drive , and firing a phalanx of ICBMs into the Starbucks across the street. In every case, all the software is looking for is a small package of data to come back and say “Thanks, that went well. Carry on”.
When software does something that is not the intended action of the user (assuming a perfect user who understands fully what the software is capable of and how to operate it) that’s called an ERROR.
An error is not a bug, or at least it isn’t yet definable as a bug as it lacks the core component of a true Bug.
What’s a bug then?
A ‘bug’, put simply, is an error or collection of related errors that can be reproduced by a second party. Reproducibility is the single most important defining element of a bug. If the error has occurred a single time for a single user (due to solar flares, power fluctuations, or hardware failure on the end users part), then we have an anomalous error and without a time machine there’s very little that can be done for those. The anomaly appears and disappears without leaving much if any information to go on. It’s when we can discover a particular sequence of actions, or specific conditions under which we get the error to reappear reliably that we can actually call it a bug and do something about it.
How to properly report a bug
My issue tracking platform of choice these days is Sifter (sifterapp.com). Not only do they provide a clean interface for keeping an eye on issues during development and and on production servers, but they have a number of great articles on the topic of bugs and reporting. I’ve taken a few excerpts from Sifter’s blog here, and if you need to report bugs to a developer I would recommend reading the full article on Sifter’s blog.
Reporting a bug in a manner that is useful comes down to the information you provide. The more of it we have as developers, the easier it can be to duplicate the error ourselves and and determine the root causes on the way to resolving the issue permanently.
What we want to know
Roughly in order of importance:
What were you trying to do? What happened instead?
Be specific here, the more detail you can provide the better able we are to reproduce the issue. “Can’t log in” is not very useful to the person trying to fix your error at 2am, so be specific:
“I tried to log in as ‘firstname.lastname@example.org’ with the password ‘password1234’ from the login window on the home page, but instead of seeing my account I went to a blank white page”
That’s way more useful, as now we can see if this is a problem for all users, or for just one or some accounts. This also tells us to check the login from homepage specifically and could help us find a problem in that template instead of searching through and debugging the whole user authentication system. More information here means faster duplication of the issue on the developer’s end and a faster resolution for the issue.
Where were you when the error occurred?
A lot of issues are situational, and only occur because of the environment that a user is in. This environment has many layers and sub questions. What browser are you in (if you know the version, tell us that too!), are you on a desktop or a smart phone? What computer, Windows? Mac? Are you connecting over Cable/FIOS or are you out in the boonies on an EDGE network?
Sometimes environmental issues can’t be resolved easily because the nature of a site or application simply demands particular resources that aren’t readily available everywhere. Knowing the constraints that a user is faced with when trying to use your site or application can provide valuable information about a bug for the development team and can direct the future of your online presence in a way that coincides with the use seen in the real world.
Was an error reported by the system?
Many systems have their own built-in methods for reporting errors to the user that encounters them (and most will also record those errors in a log for a developer to utilize later). The first step in fixing a bug is triage, that stage where we need to figure out as much about the bug as quickly as possible to start heading down the right path. If the system has popped up an error, take a screenshot (http://www.take-a-screenshot.org) or even better, copy and paste the error report into your email or bug reporting form if you’re using one. Though “Parse Error: Unexpected T_ELSE (44)” looks cryptic to the average user, to a developer that tells us nearly everything we need to know to fix the issue in minutes instead of days.
How severe is your bug?
We’re all working with limited resources in some fashion, the most universal of these limits is time. Given that there are only so many hours in each day (week, month, year, lifetime) we are constantly trying to prioritize our actions for the maximum benefit with the minimum amount of effort. To that end, understanding how to categorize a bug is incredibly important for the developers who will be tasked with this necessary maintenance work.
Here I’m cribbing directly from Sifter’s blog on the topic, as they’ve written it out perfectly already. In their system, and in general, there are a few different levels of severity that a bug can have. These are:
Critical (Aka, Fix it yesterday) – An entire swatch of functionality is inaccessible due to this problem. A great example of this would be if the authentication system for a web app was broken and nobody could login. That’s definitely critical. High (Aka, Fix it Today) – A significant piece of functionality is completely broken, but it’s isolated to a single part of the system. An example here would be if the “Forgot Password” functionality was broken. Normal (Aka, Fix it this week) – The baseline. Something is clearly broken, but it’s not stopping anyone from doing their job. A solid example here would be if a link was broken, but there were still plenty of other ways to get to that functionality. You definitely want to fix it, but it’s not high or critical. Low (Aka, Fix it this month) – We should definitely do something about this, but only after everything else is finished. This could be a typo, spacing problem, or just a minor browser issue. Trivial (Aka, Fix it when it’s convenient) – The world isn’t going to end if we don’t get to this. This will usually be enhancements or other items that are more of a personal preference nature. They’re good to jot down and keep track of, but they don’t have to be completed to launch.
The most important thing here is to honestly evaluate the severity of the issue. If it’s not preventing the majority of users from completing the majority of tasks then it’s not Critical, and probably not even High priority. In general developers will try to tackle issues from most to least important, and If you mark everything as the highest priority then it becomes easy to fix a lot of minor issues without ever seeing the one issue that is losing you users by the minute.
The most important thing to do when you encounter an issue on a site or application is to report the error with as much detail as possible to the development team or (if it’s not your site) to their support department. We all want sites that run round-the-clock and handle every task assigned to them perfectly but this is a technical impossibility so web developers and site owners must rely on our users to let us know what’s going wrong so that we can task the appropriate resources to fixing it.