Most of the time spent on a small bug is not fixing it. It is reproducing it: getting the problem to happen again on the developer’s screen so they can see the cause. A good report cuts that time dramatically, and with it the cost.
The five things every bug report needs
- Where. The exact URL of the page, copied from the address bar.
- What you did. The steps, in order. “Added the blue shirt in size M to the cart, entered postcode 3065, clicked Checkout.”
- What you expected. “I expected to see shipping options.”
- What happened instead. “The page went blank.” Include any error message word for word, or screenshot it.
- On what. Phone or computer, which browser, and whether it happens every time or only sometimes.
That is it. Five short answers turn a vague report into something a developer can usually confirm in minutes.
Show, don’t describe
A screenshot is good. A screen recording is better, because it shows the steps as well as the result. Both iPhone and Android have built-in screen recording, and so do Mac (Shift-Command-5) and Windows (the Snipping Tool can record). Thirty seconds of video often answers every question a developer would ask.
Small details that help a lot
- When it started. Did anything change around then: a plugin update, a new app, a hosting move, a new team member editing pages?
- Who it affects. Just you, some customers, everyone? Logged-in users only?
- Whether it is costing money now. A broken checkout is urgent. A typo on the About page is not. Say which so it can be triaged properly.
- Whether you have tried anything. “I cleared the cache and it still happens” saves someone suggesting it.
One bug per report
It is tempting to send one long email with everything that has been annoying you. Separate items are easier to price, fix and confirm. A short list with one line each is fine, as long as each line can stand on its own.
What never to include
Do not put passwords, API keys or customer personal details in a bug report, an email or a chat message. If a developer needs access, they should arrange it through invited accounts. We cover how in giving a developer access without sending passwords.
A template you can copy
- Page:
- Steps: 1. … 2. … 3. …
- Expected:
- Actually happened:
- Device and browser:
- Every time or sometimes:
- Started around:
- Urgency: costing sales now / annoying / cosmetic
Or skip the template: our scoping agent asks these questions for you and turns the answers into a brief. Start a brief.
