How to write a good report

Develop

are often under a ton of pressure to solve issues quickly without actually having a lot of time on their hands.

They usually face two extremes: too much unhelpful information or too little important information.

For every bug report, we highly recommend using a bug tracker like Jira implemented us a consistent, standardized approach.

Here’s how to write a good report:

1. Title/Bug ID

Keep it short and specific.

Make sure it clearly summarizes what the bug is. Having a clear title on your report makes it easier for the developer to find later on and merge any duplicates.

Examples:

❌ Bad: "I can't see the product when I add it, for some reason I try and it doesn't. WHY? Fix it asap."

vague
aggressive
too verbose
asks for a solution to be implemented

✅ Good: “CART - New items added to cart do not appear”

it helps developers instantly locate the issue (CART)
it focuses on the actual technical problem

When developers review it, they’ll be able to instantly assess the issue and move on to other elements of the bug report.

2. Summary

If your title isn’t enough, you can add a short report summary. And we mean short.

In as few words as possible, include when and how it occurred.

Your title and description may also be used in searches, so make sure you include important keywords.

Examples:

❌ Bad: "The other day I was trying to add stuff to test and nothing showed up when I did that or clicked on the button."

✅ Good: "On [DATE], I tried adding [PRODUCT] to the cart, nothing happened after clicking the 'add' button on the product overview webpage."

❌ Bad: “The design text on the pricing page looks super weird and doesn't seem right. It shouldn't look that big and should be in a different color.

✅ Good: The headline text size and color on the pricing page don't match the original designs.

3. Visual proof/screenshot

We all know that a picture is worth a thousand words. That stands true for reporting.

While it may not tell the whole story, a screenshot or video can add a lot of value by getting your developers to see and understand the problem faster.

Website annotation tools go a long way here to help you drive your point across. Feel also free to make a snapshot with your mobile and attach the mobile picture. Better a bad snapshot than none.

Example:

4. Expected vs. actual results

When you report a bug, take some time to explain to your developer what you expected to happen and what actually happened.

Example:

Expected result: ”Item should be added to the cart when I click ADD”

Actual result: ”Item does not appear in the cart”

5. Steps to reproduce

Here is your opportunity to share the steps needed to recreate the bug!

Always assume that your developer has no idea about the bug you found—how does he reproduce it?

As always, keep it simple!

The steps to follow should be comprehensive, easy to understand, and short.

The most important goal of this step is for your developer to experience the bug first-hand.

Use a numbered list here. And if you’ve already managed to recreate the issue several times, you can include the reproducibility rate (example: 12/12 times bug reproduced).

Example:

Search for product XYZ.
Click on product XYZ in search results.
Click on “Add to Cart” button.
Go to cart.

Want to go one step further? Add a short video recording, or use a session replay tool—so the developer can watch you reproduce this new bug!

6. Environment

Websites and apps can behave very differently depending on the environment used.

It’s critical that the following information be included in any report you share:

Are you a PRO User/ Gnoppix Member?
Applicaltion (Firefox, Updater…)
Operating system (OS) Live vs. Installed version
Gnoppix System Report