How to Write a Bug Report that Saves You Time and Money

Add a text field to the contact form with the label, 'Subject'.

While hypothetical, this example is not all that far away from some requests we receive at tictoc.

They may say less is more, but when it comes to bug reports or requests, not providing enough information can be a costly and time-consuming mistake for the client.

Don't make that mistake - here's how to write a bug report that will get it right first time around. 

What Makes a Good Bug Report or Feature Request?

To fully appreciate just how much detail the example feature request misses, we need to know what a good bug report looks like.

Here's how we'd write the same feature request as above, but with the information we need:

We receive a lot of submissions from the contact form on our site, http://www.example.com, and are finding the process of directing the queries to the most relevant people very time-consuming. We propose the following solution to this problem:

Add a text field to the contact form (http://www.example.com/contact_us) with the label, 'Subject'.

Currently the fields of this form are emailed to info@example.com, the new subject field should also be added to this email, below the "Surname" field. The subject line of the email should be changed from the current "Contact form submission" to "Contact: \<user-entered subject here\>".

The fields are also available for export from the admin area of the site (http://www.example.com/admin/contactformsubmissions, click the "Export" button) as a CSV, we'd like the new subject field to be added to this export as a new column called "Subject".

Please find attached an example export we've created that shows this behaviour.

With these changes we should be able to determine, from the subject of the email, the most relevant person(s) to help the user with their query without having to read the entire email.

Let's break this down.

The Problem

We begin with a summary of the problem that you're trying to solve. In proposing a solution, and in discussing potential solutions, we can always refer back to this description of the problem to ensure that the solution actually fixes it. This is the foundation of any feature request or bug report, if everyone involved fully understands the problem we will always be able to come up with the best possible solution for your problem.

The (Proposed) Solution

The proposed solution is a great starting point for an open discussion about how we might solve your problem. Wherever there are proposed changes to behaviour (in this case there are changes to the "contact us" form and the admin-only export) it is incredibly helpful to provide the URL of the page(s) which are being changed. In this case it is fair to assume that the "Contact form" appears on the "Contact Us" page, however there are far more complex examples where, without a URL, a developer may have to "fake" the problem or dig through the source code trying to find the functionality.

References above to URLs to the correct pages, the receiving email address of form data and the user journey description for the contact form export all form an excellent starting point for developers to quickly navigate to the exact parts of the relevant code for those features, allowing us to get started as soon as possible.

How the Proposed Solution Solves the Problem

By providing us with a description of how you see your problem being fixed by this solution, or how your workflow would change following implementation of your solution, we gain insight into your current workflow and can potentially see points of improvement.

The Discussion

At this point, we have enough information to suggest improvements to your hypothetical feature request:

Instead of providing a free text field for users, which may not reliably provide you with the information you need to determine its intended recipient, what do you think about changing this to a select field (or dropdown as it's sometimes known) with hard-coded options of your choice?

Depending on what the user selects from this field, we then send the email straight to the relevant email address (again, you'll need to specify these). We can include an "Other" option which can send to the default email address which we can keep as info@example.com. The "Other" option could also, on selection, show a free text field to specify a custom subject.

We've now suggested additional functionality which will almost completely cut out the need for someone to manually determine where these emails need to go, since it will be done automatically by the system. With the original one-line bug report, we could never have suggested this because we didn't have a clear idea of the problem.

This will be the beginning of what will be a very short back-and-forth to iron out any additional requirements, but we can always refer to the original problem, the original solution, and determine the best solution for you and your users.

Using the one-line request we started with we'd have to ask for this information which delays any discussion around solutions and requires additional time from Project Management, Development, Design and, most critically, you.

How to Write a Bug Report - Are there exceptions?

This level of detail is not required for every bug or feature, of course. For example, a typo on your homepage doesn't require the "how the proposed solution solves the problem" stage, however we can still apply the same principles as above.

There is a typo on the homepage (http://www.example.com), "baner" should be "banner", please see the attached screenshot.

In one sentence you've now covered everything we require. We know the problem, we know where to look on the site (the homepage), the screenshot shows us where exactly on the page we need to be looking for the typo, and we have a URL to verify that the typo exists and that we can fix it. Minutes after the task has been processed and sent to the development team, it can be fixed because you've provided all the detail we needed to go straight to the cause of the problem and rectify it.

Knowing how to write a bug report or request well won't just help to save you time and money, it'll also help you to serve your users and internal stakeholders better too. 

Let us help you find the solution before it becomes a problem. Get in touch now.