How to Write a Great Feature Request or Bug Report

There are few things more important to a project then clear and actionable direction. If you’re a freelancer, knowing what to do next makes your job infinitely easier. If you’re a client, detailing what you’d like to see with as much clarity as possible will ensure you get the end result you want.

Writing actionable feedback takes practice. That being said, there are a few concrete steps that will make feedback better for everyone involved.

Describe the Current and Desired Behavior in as Much Detail as Possible

As much as it pains me to say it, this does not go without saying. When giving feedback, you should go out of your way to explain, in as verbose a way possible, what you expect to see or experience. The preferable way to do this is in a step-by-step format given a certain scenario.

For example, if you’re testing a custom registration process for a web app, perhaps you expect to see validation of fields happening as you fill them in. Instead, field validation is happening only when pressing a “Register” button on the form. Here’s what you might write:

The username, email, and password fields are not being validated until a form submit happens. I am performing the following steps:

  1. I click on the name field to focus it
  2. I enter an invalid username
  3. I press tab or click to advance to the next field
  4. There is no indication that the name is invalid
  5. I click “Register” on the form
  6. A message displays indicating the username is invalid

I would like to see the following occur:

  1. I click on the name field to focus it
  2. I enter an invalid username
  3. I press tab or click to advance to the next field
  4. A message displays indicating the username is invalid

This is much more useful than an abbreviated description that might read as follows:

When I enter a bad username I don’t know it is invalid.

While accurate, the second version doesn’t explain the desired behavior in any way or allow for reliable replication. The recipient of the feedback can guess what is going wrong and what the desired behavior is, but can’t be sure until she attempts a fix or asks more questions, lengthening the process to get to the expected end result.

Provide Supporting Materials

Any time you’re testing something that requires input in some form, you should provide your inputs with any written feedback. For example, I recently build a form parsing engine for a client which would automatically detect appropriate labels for each input detected. Unfortunately, the engine couldn’t appropriately parse certain forms that would be popular with the market the surrounding product was entering.

The client provided me with samples of the forms that were not being parsed correctly without prompting. This gave me the ability to test, diagnose, and remedy the problem that had been discovered. Without the forms, I wouldn’t have been able to move on the problem with any speed.

As a simple rule, provide any of the following related things with each bug report or feature request:

  • Text you entered into a form field
  • Files you uploaded or used as input into a desktop application
  • Error messages you received (if any)

Take Screenshots and Record Screencasts

Have you encountered a visual bug? The most useful thing you can do is take a screenshot and provide it with any feedback. Whether a UI element is positioned incorrectly or you are seeing an odd rendering bug in a corner case, a picture can be worth a thousand words.

How should you take your screenshots? All operating systems come with a facility to capture the current output of the screen. You can reference Take-a-Screenshot.org for information on how to take perform the correct steps.

If you have access to a graphics editing application, adding text and arrows or lines pointing to the elements you’ll describe in text is very helpful.

While screenshots are awesome, there is a class of bugs that require capturing motion on your screen. Perhaps an animation is running incorrectly or some type of interaction with the application causes an unexpected result which is hard to describe. These are the perfect situations to record a short screencast.

There are a variety of screencast tools to choose from. If you’re looking for the absolutely easiest and quickest, I recommend Screenr. I prefer this tool because it allows you to download an mp4 formatted file after uploading to this service, which you can upload to a project management tool or send via email.

A Real World Example

Recently, I was working on a WordPress plugin that integrated the Forecast.io embeddable widget into a WordPress site. While doing so, I encountered a bug and reported it to the developers of the site. Here is what my bug report said:

While I was checking out the widget functionality you guys have developed (using my hometown). I found what I think might be a character encoding issue with Chrome on Windows 8.1. The red flag warning icon character doesn’t show up correctly in that browser for some reason. It displays correctly in every other browser I tested, though, including Firefox and IE11.

I’m attaching a screenshot that illustrates the issue.

I provided the following image for reference:

embed-character-issue

As you can see, I provided a description of the behavior, what I did to test the issue, and (most importantly, in this case) a screenshot that clearly illustrated what I was seeing.

Did I Miss Anything?

These are the steps I follow and ask my clients to follow when we details changes we’d like to see. Do you have any other tips or pointers? What do you like to see in a bug report?

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>