How to write a bug report developers can act on

Why bug reports come back unanswered

A developer can only fix what they can see. If the report does not let them make the bug happen on their own machine, the likely outcomes are a guess, a round of questions, or “can't reproduce”. Every one of those is slower than a report that was complete the first time.

The parts of a good bug report

1. A title that says where, what and when

“Checkout broken” could be anything. “Checkout: Pay now does nothing when a discount code is applied” tells the reader the page, the symptom and the trigger before they open the ticket.

2. Steps to reproduce

Number them, starting from somewhere the developer can get to — the home page, or a specific URL — not from the middle of your session. Include the steps that feel too obvious to mention; they are often the trigger.

3. Expected versus actual

Say both. “Nothing happens” is only a bug if something should have. Copy error messages exactly, including codes.

4. How often, and where

Every time, sometimes, or once? On which page, browser and device? A bug that only happens on Safari, or only for one account, is half diagnosed by that sentence.

5. Evidence

A screenshot shows a state; a screen recording shows the sequence that led to it. For anything involving clicks, timing or movement, a recording saves the most questions.

A bug report template you can copy

Title: [Where] [what goes wrong] [when]
  e.g. "Checkout: Pay now does nothing when a discount code is applied"

Steps to reproduce:
  1. Go to …
  2. Click …
  3. …

Expected: what should have happened
Actual:   what happened instead (exact error text, if any)

How often:  every time / sometimes / once
Where:      URL, browser and version, operating system, device
Account:    which user or test account, if it matters
Evidence:   screen recording link, screenshots, console errors

How to record a bug on your screen

1. Get to a clean starting point, just before the problem.
2. Start recording the tab or window, with your microphone on.
3. Reproduce it step by step, saying what you do and what you expect.
4. When it goes wrong, say what happened instead, and pause on any error.
5. Point at the problem — circle it, or draw an arrow — if the recorder lets you.
6. Stop, and attach the recording to the report with a one-line summary.

Any screen recorder works. With Sayvio, you can draw on the page while you record, and stopping copies a link that plays in any browser, so it pastes straight into the ticket.

Mistakes that slow a fix down

• Several bugs in one report. One report per problem, so each can be fixed and closed.
• Your diagnosis instead of your observation. “The API is down” is a guess; “the page shows a spinner for 30 seconds, then an error” is evidence.
• Missing the starting point. A recording that begins as the error appears shows the what, not the how.
• Private data in the evidence. Use a test account where you can, and never record passwords or keys.