How to report errors and document cases of website malfunction?

Purpose of bugs reporting is always the same – eliminate the problem. It is independent of the application lifecycle. Same goal applies to testers or Quality Assurance teams during production phase and to final users that work with released solution. For a start it is important to clarify crucial issue – flawless websites, applications and programs do not exist. The more complex particular solution is the more errors it contains. The vast majority of them are removed during production phase, however it is possible that some issues will slip to final release. Here is where end-user enter the arena, armed with tools and communication means with support department.

An error occurred!

First of all – don’t panic. A lot of people get flurried when facing an error and start to close all the windows and error messages – this is the worst thing that can be done. When error occurs, you need to analyze it, know your enemy. During childhood most of us used to observe small living creatures through magnifying glass. Let’s imagine that bug is such small creature. It has legs, body, colorful wings and large eyes with which it stares at us. Is it scary and will bite us? No. Therefore it is worth to look at it. If error message appears, make a screen shot. Screen shot will be useful also when web application generated suspicious URL address, empty page or just crashed. If making a screen shot is for some reason impossible, just write down displayed error message. Even though, or rather especially when it contains unintelligible for us, seemingly random strings of characters. Something that for end-users is incomprehensible, for developer might turn out to be clear message about error sources.

Second important habit, which is worth to learn, is checking repeatability. Problem will be solved much faster when developer is informed if error appears repeatedly or only once. It is worth to look at it, try to repeat activities that caused error. Maybe there is easier way to trigger that error? That information is very important for someone designated to solve reported issues.

It is worth to remember that for developer, seemingly irrelevant information can turn out valuable. Maybe bug appears only when entering long text, maybe it is caused when using diacritical marks, maybe time of activity in particular session matters? Error does not always occur because of clear and obvious reasons. Sometimes it is necessary to spend more time on it, consider what might trigger it. Obviously we rather won’t be able to provide a developer with ready solution to solve the problem, but we can help him a lot and in the same accelerate fixing time by providing our assumptions. Let’s not be afraid to use formulations like I believe that..., Problem might be caused by…, It is possible that…

Report with what?

The most popular form of information exchange between users and support department is helpline or e-mail. Those methods however have a noticeable disadvantage - lack of guidance on content and form of error report. They allow creating a single-sentence report or the one that can aspire to be printed as a brochure. Neither of those forms fosters solving problem rapidly.

Developer is satisfied when he has necessary amount of information and nothing more than that. And satisfied developer is effective developer.

Completely different form of errors reporting are so called bug trackers, solutions created especially for gathering, categorizing and managing submitted issues. Most popular ones are listed below:

• Bugzilla
  Open-source software created by Mozilla Foundation. It allows setting up entire web environment for errors reporting. As most of similar programs, it has a possibility to categorize reports by category (e.g. error, problem, suggestion), priority or repair status (e.g. new, in progress, resolved). Users can also include additional comments or attach files to their submission.
• Mantis Bug Tracker
  This is another open-source tool. Its great advantage is usage of PHP language, what makes it very versatile environment that can be used on most popular servers. Additionally to that, it is extremely developed but in the same time easy to use. There are just few seconds between registration and reporting error.
• Redmine
  Tasks management system that is very helpful when managing entire project. It offers various possibilities, like defining type of submission, its priority, description, adding attachments or comments. In our agency it is also used for reporting bugs. Main difference comparing to its predecessors is that it is rarely made available for users outside the development team.

How to report?

Well-written error report should contain those from the points listed below, that are adequate to problem’s essence. It is obvious that in case website it won’t be necessary to provide information about version – such information would matter in case mobile application. It is also important to fill each point in concise manner, including all relevant details. Let’s not be afraid to use bullet lists or provide sequence of events. Such form is in most cases sufficient, plus far clearer than long descriptions.

Title

Good title is concise and in few words informs about essence of the problem. Let’s avoid using too general phrases, like Menu is not working. It is much more valuable to say Menu items are not clickable. In case problem appears only in one specific environment (e.g. on desktops, tablets or smartphones), that can be marked here as well. It will allow assigning report to proper person faster.

Place of occurrence

Here URL or path to the location where error occurs should be provided, together with exact location on particular page.

Examples:

• http://example.com/build/home.html – menu bar.
• Enlarged image in “Our team” gallery.

Environment

Another crucial matter is to provide environment in which error was noticed. In case web applications and websites it is necessary to inform about version of browser and operating system. Similarly in case errors appearing on mobile devices – we should provide device type, operating system version and internet browser.

It is slightly different in case software, or custom mobile applications. Here, besides operating system, it is also worth to give distribution number (so version of the application or program). In case error is related with graphics, it might also help to provide configuration of the machine on which it was spotted.

Let’s not be afraid that any of the above data will be used in inappropriate way. It will be used only to diagnose source of the problem. It often happens that problem appears only in specific hardware and software configuration. In order to avoid endless messages exchange with support department, it is better to provide all useful information on the beginning.

Reproduction path

Developers love concretes and the path to reproduce an error is frequently necessary to fix it. Unfortunately there is always a chance that developer will reject our submission in case he won’t be able to see described bug. That is why we should always include set of activities that resulted in error occurrence.

Path can be really simple, for example:

1. Add product to cart.
2. Enter cart.

It can also be much more complex, for example:

Find product with discount price - add product to cart - increase amount of this product to 3 - update entire cart.

Form, in the way reproduction path is provided, is free. Let’s just keep the following rule in mind: the simpler the better. For sure long, complex sentences should be avoided. On the other hand let’s not be afraid to repeat: error submission is not English test. Although correct spelling and punctuation are welcome, repeats are by all means acceptable.

Additional information

In this section our presumptions and suggestions should be included. It is always worth to add if error appears constantly or did it appear only once. Does it occur occasionally in seemingly random situations? Such information will significantly increase time of problem identification and repair.

It is also good to provide ones expectations regarding expected result. This way support team receives information how particular solution is understood and received by users. Besides developer gains knowledge, whether he deals with a bug or error in application’s logic.

If we feel capable to do so, we can also include our presumptions regarding source of error. Let’s not exaggerate, just include short memo with our assumptions. No one expects that we will provide ready solution. Of course developer will appreciate the fact that we have spent our time trying to understand the problem that is reported.

Summary

Error submission might seem to be hard activity, full of loopholes and dead ends. Perhaps you have impression that error won’t reach a developer and instead will stuck somewhere in support department structures. The truth is that all you need to keep in mind is one simple rule – be precise. The more detailed description the better results, also in terms of repair time.

Finally, before deciding to contact support again, being impenitent with long awaiting time, be aware that your submission might not be the only one and support team most likely already received many calls regarding this issue. Just be patient and give developers time to implement amendment.