How to write an effective bug report to make web development easier?

What is a bug report? Why are bug reports important? What questions to answer before writing a bug report? What to include in a bug report?

If you are someone from the software world, you actually know what a bug is. If you are new to this space or just curious to know what am I talking about, let me define it for you.

When any software element or workflow does not behave in the way it is required to behave, it is referred to as a bug. In simple words, a bug is: any deflection from the desired behaviour.

When there is a deflection, it needs to be reported and corrected. But, how that bug would be handled at the developer’s end; depends on how the bug is reported.

What if the developer is not able to understand the bug in first place? What if the bug can’t be reproduced at developer’s end? What if it’s a half cooked story that lacks required environment and browser information?

What do you think, is the future of such a bug report? It will be labelled as either ‘Works for me’/ ‘Cannot Reproduce’/ ‘Duplicate’/ ‘Not a bug’ and trashed.Thus, all the effort of finding the bug goes in vein and more importantly even after getting noticed the bug still exist in the software.

So, how to write a bug report that does not get trashed? For this first you need to understand what answers you should have ready, before starting with documenting the bug report.

Prerequisites for writing a good bug report?

For writing a good bug report, you need to get the following answered:

Is it actually a bug?

You need to sure that what you want to report is actually a bug or not. Sometime we end up reporting suggestions, enhancements new feature requests as bugs. But this should not happen. You need to clear in your head that whether you want to get some functionality fixed(as it is not working in accordance with business requirement specifications) or it is something based on your personal experience(while testing the software) that some functionality should follow this workflow rather than the existing one.

Do you know the exact steps to reproduce it?

Would you report a bug as soon as you encountered it? For me it’s a no as before reporting an issue, I need to be sure myself that it is a bug that can be reproduced following this set of steps. Sometimes you encounter some anomalies due to internet speed, browser cache, etc. If you can reproduce the same bug with same steps twice or thrice then only you can be sure that the bug exists and needs to be fixed. Next thing you need to do is clip off any extra steps from the sequence and come up with an optimal step sequence to reproduce the bug.

Is the bug valid only for specific environment/browser/mobile device?

Some bugs are generic bugs but some bugs are dependent on certain constraints like screen size, browser or browser version, operating system, etc. If the bug to be reported has any such constraints you need to figure out them before actually reporting the bug.

Are you reporting one bug or multiple bugs?

Sometimes you end up reporting 2–3 bugs in one bug report. Although the best practice is to go with one on one approach as it makes tracking bugs easier; but you can always choose to add more than one bug too under the same header. It depends on type and nature of bugs. But whenever you are reporting multiple bugs as one then you should know it before hand and should add them as a checklist so that they can individually handled at micro level.

Do you need a screenshot or short video to explain the issue better?

Visuals act better than words, so in most cases you generally use a screenshot or short video to demonstrate the bug for better clarity. If you need a visual reference to attach to the bug report, then keep it handy before getting into documenting the bug report.

Is it a known or duplicate bug?

Duplicate issues are a wastes of time and efforts. It’s better to avoid them. before actually reporting the bug make sure you are not adding a known issue. Check the repository before starting with the bug report. This gives you dual benefit:

• Ensures that its a new bug.
• Alarms you if any previously fixed bug has reappeared.

Are you testing the latest version of the software?

Sometimes due to confusion or misunderstanding you are testing some older version of the application which has already been updated. To avoid such a scenario, please make sure that you are testing the correct application version.

Once you have these answers ready, then you can proceed with writing a bug report. A good bug report is documenting the bug in such a manner that the bug can be easily understood, tracked and referred back to. A good bug report filed and maintained using a bug tracking system completes the package. Now lets move to the core question: What to include in a bug report? To make it an effective bug report that developers would love to read.

Checklist-What to include in a bug report?

A good bug report includes:

• A unique Bug Id — to spot and track the bug.
• Product and version — to know for which product and version the bug exists.
• Module/Sub-Module/Component — to know where the problem is.
• Crystal clear bug title — to let others know the problem.
• Bug description — to mention consolidated steps to reproduce the bug.
• Bug Type — to identify if it is a bug/Enhancement or New Feature.
• Screenshot/video — to act as a visual reference.
• Bug capture date and time — to know when the bug was observed.
• Bug priority and severity — to know how and when to pay heed to the bug.
• Browser and OS details — to know the environment to reproduce bugs.
• Screen size — to know the device type.
• Bug Status — to know the current bug status(open, to do, fixed, etc.)
• Tags — to make the bug discovery easier at later stages.
• Reporter — to know whom to contact if any further info is required.
• Assignee — to know who needs to look at the issue.
• Console errors — to make it easy to debug.

Now you know the key elements of an effective bug report, but there is one more thing you need to understand. While reporting issues you need to be patient enough as all the bugs you are reporting today won’t be fixed by tomorrow. There would always be some bugs that will keep lingering for weeks or even months. But this should not stop you from reporting the issue. Even if its a minor issue you need to defend it, that it exists and it needs to be fixed. Basically you need to overstate the broken condition of the software and provide all the relevant info required to fix it. That’s all!

We have developed zipBoard trying to keep things as simple as possible and only focus on details that would make the collaboration process easier. If you are looking for such bug tracking tool do checkout zipBoard. It allows you to annotate, collaborate, assign tasks, and to do responsive testing for your webdev projects. It also allows you to gather feedback from various stakeholders and track progress.