Fix your product issue with a problem report

Damn it! You just found a bug. No problemo. Keep cool. And let’s fill out a problem report to organize the resolution.

What is a problem report?

It is a file where you describe an issue encountered with a product. The purpose is to fix it the most easily and rapidly possible. The product may be a software, a website, a device…

We call it problem report but you can also find it under the following names:

Every company has its own name for it.

Depending on who writes it (a user, a customer, a software developer…), the level of details, the precision may vary. The amount and quality of data collected will directly impact the resolution process.

The purpose of a problem report is to gather all the data required to describe it, to reproduce it and to understand it in order to fix it faster, better and make this issue never happen again.

The difficulties in making a good report

The level of details

The more details we gather, the easiest it will be to reproduce and to resolve the problem. But what piece of information is relevant? Which one is useful?

You need to have a problem report template to fill with a list of required items you usually need to fix the bug. Everything may not be always used depending on you activity. But the more you populate this template with what you usually need, the quicker it will be to surround the problem.

Can the error be repeated?

This is the main issue with a bug: can we reproduce it? We can investigate only if we can make it happen again. So we not only have to give enough details to recreate the environment in which the bug appears. But we also have to precisely describe the sequence of actions that led to it.

If we get to systematically reproducing the bug, we have done 99% of the resolution.

Who did it? (Accountability of the error)

A bug is a bug.

• a human error from a developer
• a product misuse
• a lack of maturity in the specifications
• …

Depending on who or what is accountable for it, the way to solve it can be different. It might even not be a problem at all.

(Some people might say the problem is located between the keyboard and the chair)

Two propositions for a problem report

Proposition 1 : the “quick and dirty”

A good problem report, from the effort / quality ration point of view, is to simply record the problem on a camera. Use the camera from your smartphone or a screen shot software, and make it happen.

You may deliver a very good material to the person in charge of solving the problem. It will do the work in most of the cases.

Obviously, depending on the context, it might not be easy to shoot the issue. You may not be authorized to use a camera, the problem can be located in a non-reachable place, etc. That’s why we have a second solution.

Proposition 2 : the “good old exhaustive description document”

Here is what we suggest you to describe in your problem report:

• the configuration
• the problematic behavior
• the expected behavior
• some clues to solve the problem (if you have any)
• your workaround (if you found one)

We will detail those items in the following parts.

Configuration

Describe the whole context, the whole environment, in which the problem happened.

If the bugged product is a software, give its name and its version.
If it is a device, give its model and its serial number.

The purpose is to identify the subject of the bug, so the person in charge of solving it would be able to repeat the problem.

Problematic behavior

Explain why the behavior you experience is problematic. Describe what it does wrong. Do not hesitate to join any illustration that would ease the understanding of the behavior: a video, some pictures, some screen shots, …

The person in charge must be able to recognize this behavior thanks to your description. So he knows how it happens and can track the problem.

Expected behavior

Now explain what you were expecting from the product? How, in your opinion, the product should match your need, what you want it to do?

Maybe, the problematic behavior that you described, was not a problem at all. Maybe the product can’t do what you want it to. In this case there is a lack of good user experience, a lack of ergonomic design. The way to do what you want may not be very clear.

In any case, describing what you were expecting is a good insight for telling how to fix the problem and match the user expectations.

Clues to solve the problem

These are additional items to give to the corrector, if they are not already in the expected behavior.

If you know the technology behind the product or you already have some experience with it, you may have intuitions about what is wrong and how to fix it. This knowledge, shared with the corrector, may save him hours or even days in the resolution process.

Workaround

This too is optional because there might not even be a workaround.
Despite the bug, do you manage to get what you want? If so how do you do it? How do you “bend” the product to match your need? What is your trick?
The doors is blocked? A workaround is to enter through the window.

Giving a workaround to the corrector shows him how you use the product. It can give several pieces of information:

• how to improve the user experience
• what are the non expected uses of the product? Sometimes the customers uses a product in a complete different way than what it was designed for. Originally the Coca Cola was a medication
• what is the criticality of the problem? If the workaround is acceptable, at least temporarily, some more critical bugs can be prioritized.

The process of a problem resolution

Create a problem report is the first step of solving it. The bug discoverer (let’s call him the user) still has a role to play during the resolution, so keep in touch!

In the following parts, we tell you our own resolution process.

1. The discovery

The bug happens. The user discovers it. He writes a problem report in a text editor or in a dedicated software (see a list of them at the end).

Then he sends this report to the person in charge of fixing the problems aka the corrector.

2. The discussion

The corrector takes notice of the report. He tries to reproduce it by himself to see if he understands the report well enough. If he doesn’t manage to make the bug happen, there might be a lack of information. So he engages a discussion with the user to gather all the required data.

3. The resolution

Once the corrector has all he needs, he can starts his inquiry to understand what is wrong. He tests the product, try some changes. The length of this step depends on the complexity, and the priority, of the problem.

The user isn’t implied at this point.

4. The validation

Now, the corrector considers the problem is solved. It is very important he agrees with the user about this resolution. It is up to the user to close the case or not.

Unfortunately, it is far too often that such a decision is made only by the corrector. In most of the case, the resolution is satisfying. But if it is not, it may be because of a misunderstanding or a lack of information. In this case the user is back at the beginning with the bug and it is usually very difficult to reopen the closed resolution process. This is why he must be implied in the validation of the resolution.

Ideally, here is what happens: the corrector shows the user the resolution. They do several tests together to check its strength of the solution.

If the user is not satisfied, we go back to step 2 : the discussion.

If the user is satisfied, the case is closed.

Some resources to build problem reports

There is a lot of software (bugtracking softwares) and templates to write problem reports and / or to engage resolution processes. Here are some of them:

Gitlab : this is the one we use. It is a freemium and its free features are very satisfying. Besides the bugtracking is one of its many services. It even allows creating problem report through an e-mail. You send your pre-formated e-mail to a specific address and its message is converted into a report and initiates the process.

Github : an online freemium similar to Gitlab with some of the same features. We use it for our open source projects.

Mantis Bug Tracker : you can install this one onto your company servers. It is free and open source. Highly customizable, it is entirely dedicated to the bugtracking. We did use it a lot in a previous life.

A template on Trello : you probably already know Trello, the project management software based on the kanban method. Here is a template build to raise and manage issues.

Conclusion

Bugs, errors, problems are an unavoidable load that a project must carry, whatever the activity. The resolution process depends a lot on the fields. Our propositions here try to be as universal as possible. They have been experienced with success in web developments, aeronautics, automobile…

They are relatively complete but you’ll probably have to adapt them to your own processes to make them even more efficient.

There is another process close to the problem resolution which is the improvement suggestions management. This is when users tell you what new features they’d like to have with the product. This will be the topic for another article but to have an overview you can read our french article about collective intelligence and this second one about Fider a software to collect suggestions.

[Medium] Managing Remote Teams — Use Checklists by Eric Eliott
[Book] Getting Things Done — David Allen

Which tools do you use to solve issues during projects?
What are your methods?
Do you have any different processes different from those presented here?
Please share with us your experience!

Originally published at https://www.naept.com on October 9, 2020.