TL;DR:
A good bug report lets someone else make the problem happen: steps to reproduce, expected versus actual result and the environment.
Ask the customer only for what you cannot find out yourself, and ask one clear question at a time.
Separate what you observed from what you guess the cause is.
A customer writes: "Your checkout is broken, I've tried three times." That is a real problem described in a way that nobody can fix. An engineer reading it has to ask what was in the cart, what happened, on what device and what was supposed to happen. A good bug report answers those questions before anyone has to ask.
When to write one
Write a bug report when you suspect the product is at fault rather than the customer's setup, and you have ruled out the quick explanations. If you are unsure, a report with the facts you have is still more useful than a forwarded email.
What to have ready
The customer's message and ticket link.
A test account or the customer's consent to look at their account details, following your company's privacy rules.
A place to take notes and screenshots of what you do.
The bug template your team uses, or the one below.
Step by step
Underline the facts in the message: Note what the customer did, what they saw and when. Ignore opinions for now.
Ask for what is missing: Send one short message with up to three questions, such as the device, what they were buying and the exact words of any error.
Try to reproduce it: Follow the customer's steps on a test account and write down each click as you go.
Write expected and actual separately: Expected is what should happen. Actual is what did happen, including exact error text.
Record the environment: Device, browser or app version, and whether signed in.
Add evidence and a severity: Attach screenshots and ticket links, and say how many customers are affected.
Describe the impact, leave out the diagnosis: Say what you saw. Leave the cause to engineering, or label any guess clearly as a guess.
Worked example: a message about a broken checkout
The customer and shop are invented. The message reads: "Your checkout is broken. I've tried three times and it just won't go through. Super annoying."
First, the facts in it: three attempts, checkout, no success. Missing: what was in the cart, which step failed, what they saw, and on which device. You reply with a friendly, short message:
Note: Sorry about that, and thanks for trying three times. Could you tell me: (1) what device and browser you are using, (2) what happens when you select Pay, and (3) any message you see on the screen, word for word? A screenshot would be great if you can.
The customer answers: Safari on an iPhone, the page shows a spinner and then returns to the cart, and the message says "Something went wrong." You now try the steps on a test account in the same browser if you can borrow a device, or the closest you have, and the same thing happens. Write it up:
Title: Checkout returns to cart with "Something went wrong" after Pay
Steps to reproduce
1. Add any item to the cart
2. Go to checkout and enter the test shipping details
3. Select Pay
Expected: order confirmation page
Actual: spinner for about 5 seconds, then back to cart with "Something went wrong"
Environment: iPhone, Safari, signed in, test account
Reproduced: yes, 3 of 3 tries (support test)
Impact: 1 customer reported, 3 attempts; no other reports found in the last day
Severity: S2 (one customer blocked; core feature may be affected)
Evidence: ticket #210 (made-up), screenshot of the message
Not yet tried: other browsers, other payment methodsCheck the report against the three musts. Steps to reproduce: three numbered steps anyone can follow. Expected versus actual: stated separately with exact error text. Environment: device, browser, signed-in state. It also says what is not known, which saves the engineer from assuming you checked everything.
The "3 of 3 tries" line matters. A problem that happens every time is easier to catch than one that happens occasionally, and engineers want to know which they are dealing with. If it had happened only once in three tries, the report should say "1 of 3" and mention anything different about the failing try.
Give the report a title that describes the symptom and the place: "Checkout returns to cart with an error after Pay" is searchable and clear. "Checkout broken" matches every future checkout bug and tells nobody anything.
Finally, keep the customer informed without promising a fix. Tell them you have passed on a clear report and when you will next update them. Then, when engineering replies, close the loop in the same ticket so the history stays in one place.
Mistakes to avoid
Forwarding the customer message as the report. It has the feeling but not the steps.
Asking five questions at once. Customers answer one or two. Ask the three most useful.
Mixing the cause in as a fact. "Payment provider is down" is a guess unless you have confirmation.
Leaving out what you tried. Engineers waste time repeating your checks.
Sharing private details. Keep card numbers and passwords out of tickets and screenshots; never ask a customer for them.
Doing it faster
Keep the template as a snippet and fill the fields as you reproduce, step by step, instead of writing afterwards. If you record your screen while testing, you can write the steps from the recording. DuckyHelper is there to talk it through out loud if you want a sounding board while you work, but the report is yours to check.
Frequently asked questions
What if I cannot reproduce the problem?
Say so in the report, list what you tried, and keep the customer's exact description. A report that says "not reproduced" is still useful.
Do I need a screenshot every time?
No, but include one when there is an error message or the screen looks wrong. Exact text is better than a description.
Get started
