Open Main Menu

Website de-bugging process and tips

July 08, 2016

Trouble shooting or de-bugging most things is not particularly hard, so long as we have a good process in place. The automotive world uses a process known as the 4 C’s: Complaint, Cause, Correction and Confirm.

First, the error must be reported and a complaint created. Next we need to replicate the issue and determine the cause. We craft a solution, implement the solution, and confirm our solution has corrected the complaint.

This fantastic workflow can be applied to near any kind of de-bugging. I approach website debugging with this same model.

Complaint

The complaint phase is often the biggest pitfall of most website debugging processes. Most often a developer will get a call or email which says, “(something) doesn’t work”. This is not particularly helpful to the developer as it has very little detail to go on.

The immediate reaction, for many developers (myself included), is – “That can’t be. It always worked before”. This knee-jerk reaction is hard to stop but is not helpful. It prejudices and taints our efforts moving forward. It is not surprising, then, that many of us fire up our preferred browser, check the thing, and reply – “Works for me”. Case closed.

In order to kick off a more fruitful de-bugging session, developers need a better complaint and as developers we need to help our clients here. Maybe you create a quick and dirty form for the customer to fill out when there is an error reported to them. Don’t get too detailed, but do gather some quick details.

  • Date and Time
  • User’s contact information for follow up questions (name, email and phone number)
  • Description of the error, including basic steps on how it was introduced

If possible …

  • User’s browser (Chrome, Firefox, Safari, Internet Explorer, Edge, Safari, Opera)
  • User’s device (laptop, desktop, tablet or phone,) and Operating System (Mac or PC)

Most end users will gladly provide this information and will appreciate that you care that they had a poor experience. More often than not, they will gladly participate in the de-bugging process. The key here is to facilitate dialog as opposed to finger pointing or assumptions.

The client can have this form printed out, and kept in the office. Even better – a digital form the client can fill out and email directly to the developer. Why not automate the process, and have a “tech support” link on every page that opens a form which the end user fills out, and is sent direct to the developer?

However the information is gathered and sent, the more the developer has to work from the better. It is near impossible to have too much detail or data when trying to fix an issue.

Cause

Determining cause is much easier if you have good clues to draw conclusions from. A solid complaint will go along way. As developers, we can bake in de-bugging tools.

A major complaint is contact forms not working properly. Any good contact form should include:

  • the URL of where the form was filled
  • the date and time of submission
  • the IP address of who submitted the form

These details will go a long way in determining the cause of an issue. Although these details could trigger a spam filter if included in every email submission, they could easily be dropped in a local database, along with the rest of the contact form details, prior to the form being sent. You now have a multi-step process which is more complicated and possibly more prone to fail, but one which provides baked in diagnostics.

What about really long forms (the kind that typically break) or even worse – an online store? Here is where your old friend Google Analytics really comes in handy.

Google Analytics (or access logs) as a de-bugging tool

First off, you should set up a lot of goals and / or event triggers for any website. Set up goals for reaching forms and checkout, as well as for completing the form or the checkout process. This let’s us see how many folks reached the conversion point as opposed to those that went on to convert. Knowing that success rate helps tremendously.

You can go further than that. Break those long forms up into multiple pages, and create goals for each step of the form. Create a goal for each step of the checkout process. This allows us to pin down where in a process there is a failure.

Keep digging into analytics.

Users typically report complaints as soon as they hit trouble, so we can work backward from when the complaint was issued. If we have a good complaint, it will tell us, on this date, shortly before this time, a user encountered an error.

We can then go to Google Analytics for that day, and look at the data hourly. By narrowing down the error to a specific hour, we can sometimes use other Google Analytics data to learn more. We might be able to dig out the exact browser and device (as opposed to generalized information). We can compare that data to other hours and days, other browsers and devices. This detective work often reveals a pattern of failure we can then correct.

Another handy tool to have in place is at least three versions of the site (live, dev, and test). Ideally, things are developed on dev, tested on test and then pushed to production on live. This means, in theory, that all three match at all times. The reality is that they often do not, but this can be very helpful. If a bug presents in production, you can compare it to test and dev (or any other instances you might have). Sometimes comparing and contrasting different versions can highlight the issue.

Along the same lines, it pays tremendous dividends to create regular backups. Backups can often be created programmatically, but they should certainly be done before and after any major changes. Even if you do not have active installations of various versions of the item in question, being able to recreate an older version might help determine the cause. A major advantage of digital work is that we can often roll the clock back to a time when the bug did not present itself.

Correction

Having tracked down clues, and replicated the issue, crafting a correction is typically easy. Use data to draw your conclusions, and always think outside the box. It was an error that made it to production because it is an oddity, not the norm.

As you work the issue, you may employ a number of techniques. One common approach is maintenance as repair. In the digital world, our systems are highly dynamic and always responding to change. If you come across a system in need of updates, run a backup, update everything (maybe on dev), and see what you get. Sometimes the correction is as simple as basic maintenance.

Another way to look at this methodology is from the perspective of “known problems first”. If you have a system that you know has issues, however unrelated they may seem, it might be helpful to correct those issues first. The more complex a system becomes the harder it is to understand how each part might impact the whole. The best approach is to forget all assumptions and correct anything you see as irregular, malfunctioning or broken. Sometimes you get lucky and a bug that seems unrelated corrects a host of other issues.

The converse of “known problems first” is just as valid, and relies on weighing the value of comprehensive repair vs. fixing what is broken. Sometimes you have an old system that is fragile, but generally getting the job done. It might be something that is only going to remain in service for a relatively short period of time. In these cases, it can often help to put on blinders, ignore the chaos within you are working, and solely fix what is “broken”. This approach often leads to a quick and dirty fix to what ails us without wasting time or money. It is a judgement call but is no less valid of an approach to repair.

An approach I leverage from my experience with cars is “known good part”. In this case, you may not know what is wrong with a system. In order to diagnose and fix an issue, you methodically replace parts of the system with “known good” replacements. In the automotive world, this is slow and expensive. In the digital world, it is often a quick and easy way to fix bugs. Even if there is not an update present, you can often re-install a fresh copy. Computers are not perfect and updates often fail to install correctly. Sometimes a manual replacement of a section of code will correct an error despite no “update” being made.

Much in the same vein of “known good part”, it is best to isolate where possible. If something is not working within a system, remove it from the system and test it on its own. This can be done locally, on a dev server or in a sandbox like codepen or codesandbox. If the apparently malfunctioning piece works in isolation, you might consider removing other elements from the system and testing further. There are times where pieces all work in isolation but not in combination. You may find that your correction is not to change any individual piece, but to not use certain items together (i.e. loading scripts only where needed, not everywhere).

As you go down this path, consider simple things like the server where everything is hosted, SSL certificates, or even the item’s location within the server. Never make assumptions about anything and assume that any piece might be at fault, however far in the background it might seem.

The final thought on correction would have to be this; the biggest failure in most de-bugging processes is that folks stop here. You have to go one step further

Confirm

The last step is to confirm the correction … 1. actually fixes the problem and 2. does not cause another issue.

If you have the end user’s contact information, have them check too. You may need to walk them through the process of clearing their cache, but hey – that’s life.

Not only will this help you confirm your correction, it will also help solidify that user for your client. In turn, your client will be extra thankful for your dedication to fixing the issue for the end user. It’s a win-win situation.