Authors
James Nettik
Senior Developer Manager
Have you ever owned a chainsaw? When I was a teenager, I was helping my dad with something in the garage. I don’t remember what we were working on, but I do remember it was the last thing on Earth I wanted to be doing. Since this was before social media and mobile phones were the distractions they are today, I found myself reading the instruction manual of our chainsaw. While wading through pages of safety disclaimers, I came across one that made me pause.
This seemed like such obvious advice. Surely people using a chainsaw would know better than this. And yet, there it was, sitting next to an exclamation mark inside a giant red triangle.
That’s how I imagine this post is being taken. Some of the things I’ll go over might sound like common sense, but they’re things that are still worth discussing. The consequences of not following this advice may be less severe than with the chainsaw, but they will help improve communication between you and your developers. And better communication can reduce wasted time, which can reduce wasted money.
Great expectations
The word “broken” is very subjective. Say you’re on the last slide of a carousel, and clicking the “Next” arrow does nothing. Your expectation may be that you get returned to the start of the carousel, and see the first slide again. If your experience isn’t aligning with your expectations, it’s easy to say something is “broken”. However your developer, if not aware of those expectations, could see things as working properly. The carousel still functions, and there might be reasons why it stops on the final slide.
Admittedly there are things that aren’t so subjective. If you click the “Submit” button on the contact form, and the site goes away completely then that’s very clearly “broken”. What still may not be clear are expectations. Should the user be sent to a page thanking them for their submission? Perhaps we want to send them to the home page, with a message thanking them. Should email notifications be sent out, and to whom?
Detailing your expectations as well as the problem goes a long way to creating bug reports that are immediately actionable for your developer.
The Devil is in the devices
We currently live in an ever expanding combination of devices, operating systems, and browsers. Within those combinations are varying types of interactions, capabilities, restrictions, and quirks. This photo has always left an impression on me of what the landscape is like for building on the web these days.
The following is always helpful to know when starting to debug an issue:
- What device are you on? (e.g. Laptop, iPhone, Microsoft Surface, etc.)
- What operating system are you using? (e.g. Windows, OSX/Mac, Android, iOS, etc.)
- What browser are you using? (e.g. Internet Explorer, Chrome, Firefox, etc.)Knowing the version of the browser can also be helpful. If you happen to know this, then including it is always welcome information.
“I’m sorry Dave, I’m afraid I can’t do that.”
Often times, when things go wrong with computers, the computer will let you know. Sometimes computers passively nudge you, “Oh by the way, something didn’t quite work right”, and then lets you carry on with your task. Other times, computers throw an incoherent tantrum full of gibberish, take their toys, and go home.
Whenever your bug is accompanied with an error message, it’s always important to include that. I often joke that my job title should be “Professional Googler”. More times than not when things break, the developer will have no idea how to fix it. An error message is a great place to start the search, as it gives us something tangible to search for. It might be our first time encountering this error, but odds are good someone else has and documented their fix.
Screenshots of the error are good. I can read the text, and start working. Copying and pasting the message directly in the report is even better. Errors can get very long, and trying to retype them gets tedious and accident prone. Being able to directly copy the message out of a ticket and into Google makes searching much faster. Sometimes, it’s the little things that make a world of difference.
Walking a mile in your shoes
Some issues on a website may only be specific to a certain subset of users, and only under certain conditions. Knowing those specifics from the start can really speed up how quickly a developer can recreate and start fixing a problem.
Explaining what actions you were taking, and on what pages (including specific URLs) helps take the guesswork out of seeing the bug ourselves. Were you logged into the website when you found the issue? Including that user’s info allows us to test more accurately, and eliminate the possibility that the problem is specific to only that type of user.
The faster we can get to seeing the problem on our screens, the sooner we can start fixing it. This can be difficult. Sometimes for complex issues, setting up a screen share with the developer to demo the bug in real time will save a lot of miscommunication. Once those details are visible, they can become easier to document in a ticket.
Organizing the chaos
As with most things, improving communication helps everyone. Few things can be as stressful as finding a bug on your live website. Even fewer things can be as frustrating as a bug that’s difficult to reproduce. This is true regardless of whether you’re the person reporting the bug, or the person fixing it. Both people want the same thing, to get this fixed fast.
So what does all of this look like in practice then? Going back to our problematic carousel from earlier, let’s report this to the developer. This should hopefully serve as a checklist of things you can use when filing your own bug reports.
Issue: Site carousels stop scrolling at the last slide.
Steps to reproduce:
- Page through carousel slides until you are on the final slide.
- Click the “next” arrow.
- Carousel remains on the same slide.
Expectations: Carousel should animate as normal; starting over, and showing the first slide.
Relevant Links: - http://www.mysite.com/
- http://www.mysite.com/blog
Device: Laptop
Operating System: Windows 10
Browser (version if known): Internet Explorer 11
Error messages: NA
Username: NA
With this information, the developer now knows the problem, how to experience it themselves, and what needs to change. They also know how and where to test their changes to make sure things were fixed properly.