Blog · Working with developers
How to write a bug report developers can act on
"The checkout is broken." Every developer has received a message like this, and every one of them has had to reply with questions before they could start. A clear bug report saves that back and forth, and gets the problem fixed sooner.
You do not need technical knowledge to write a good bug report. You need to describe what you saw in a way someone else can repeat.
Why good bug reports matter
Developers cannot fix what they cannot see. The first step in fixing a bug is to reproduce it: make it happen again on purpose. If they cannot, the report sits in the backlog while people trade messages. A clear report can turn a day of confusion into an hour of work.
What to include
1. A short, specific title
Say what is wrong and where. "Checkout button does nothing on mobile Safari" is far more useful than "Checkout broken".
2. Steps to reproduce
List exactly what you did, in order, starting from somewhere anyone can reach:
- Log in as a customer
- Add any product to the basket
- Open the basket and tap Checkout
3. What you expected
"The payment page should open."
4. What happened instead
"Nothing happens. The button changes colour but the page does not change."
5. Where it happened
- Device and browser, such as iPhone 15 with Safari, or Windows laptop with Chrome
- Which version of the product: live site, staging or the app
- Your account or user type, if it matters
6. Evidence
A screenshot or short screen recording is often worth more than a paragraph. Include any error message word for word.
7. How serious it is
Say how many people are affected and what it costs the business. "No customer can pay on iPhone" is urgent. "The footer link is slightly misaligned" is not. This helps the team set the severity correctly.
A bad report and a good one
| Bad | Good |
|---|---|
| "Login doesn't work" | "Password reset email never arrives for Gmail addresses" |
| No steps | Four numbered steps from the login page |
| "It's broken for everyone!!" | "Happens every time for Gmail users. Outlook users are fine." |
| No screenshot | Screenshot of the reset page and the empty inbox |
A copy-and-paste template
Title: [What is wrong] on [where]
Steps: 1. ... 2. ... 3. ...
Expected: ...
Actual: ...
Device and browser: ...
Environment: live, staging or app
Evidence: screenshot or recording attached
Impact: who is affected and how badly
What happens next
A developer will try to reproduce the bug, find the cause and fix it. They may reply with terms like "cannot reproduce", "edge case" or "regression". If a reply confuses you, paste it into Plainlee for a plain explanation, or check our tech glossary.