Write It Down
A bug report should be so clear that a developer can fix it without asking a single question. Learn the anatomy of a report that gets results.
1 The Hook — Why This Matters
In 2019, an IRD payment portal failed during tax season. A tester found the bug on day one and reported it as: "Payment page is broken." The developer read the report, tried the main payment flow, and it worked. They closed the ticket as "cannot reproduce."
Three days later, a second tester filed a detailed report: "Login fails with Safari when using saved password." It included exact Safari version, macOS version, steps with a saved Keychain password, and a screen recording. The developer reproduced it in five minutes and shipped a fix the same day.
The first bug report wasted three days. The second saved three days. The difference was not the bug. It was the report.
2 The Rule — The One-Sentence Version
A bug report should be so clear that a developer can fix it without asking a single question.
Every question a developer asks about your report is time lost. "What browser?" "What did you expect?" "Can you show me?" A good report answers these before they are asked. Writing it down well is a technical skill, not an afterthought.
3 The Analogy — Think Of It Like...
Reporting a leaky tap to a plumber.
"The tap in the kitchen drips twice per minute, only when the hot water is on, and it started after last Tuesday's maintenance" gets fixed fast. "There's water somewhere" gets ignored. A bug report is the same. Specificity is the difference between action and ambiguity.
4 Watch Me Do It — Step by Step
Here is a real NZ example: writing a bug report for an IRD payment issue. Follow these steps every time you find a defect.
Scenario: You are testing the IRD payment portal. After entering a valid IRD number and selecting "Pay by credit card," the "Continue" button does nothing on Safari.
- Write a specific title The title should summarise the what, where, and when. "Continue button unresponsive on Safari after selecting credit card payment." A developer should know the general issue from the title alone.
- Add a one-sentence description Expand the title in plain language. "After a user enters a valid IRD number and selects credit card payment on Safari, the Continue button becomes unresponsive and the user cannot proceed."
- List preconditions State what must be true before the bug appears. "Safari 17, macOS Sonoma, user logged in with verified account, valid IRD number entered."
- Write numbered reproduction steps Every step must be precise enough for a stranger to follow. "1. Log in. 2. Navigate to Payments. 3. Enter IRD number 123-456-789. 4. Select 'Credit card'. 5. Click 'Continue'."
- State the expected result What should happen? "User is taken to the credit card entry form."
- State the actual result What actually happens? "Nothing. The button shows a click animation but the page does not change. No error message is shown."
- Document the environment Browser, OS, device, screen size, and any extensions installed. "Safari 17.1, macOS Sonoma 14.1, MacBook Air M2, 1440x900, no extensions."
- Attach evidence A screenshot or screen recording is worth a thousand words. Attach console logs if there are JavaScript errors.
| Element | Bad report | Good report |
|---|---|---|
| Title | "Payment broken" | "Continue button unresponsive on Safari after selecting credit card" |
| Steps | "I tried to pay" | Numbered, specific, reproducible |
| Expected | Missing | "User taken to card entry form" |
| Actual | "It didn't work" | "Button animates but page does not change" |
| Environment | Missing | "Safari 17.1, macOS Sonoma, MacBook Air" |
| Evidence | Missing | Screenshot + console log attached |
The bad report would be closed as "cannot reproduce." The good report would be assigned, reproduced, and fixed in one cycle.
Intermittent bugs: documentation saves time on repeat issues
A bug happens sometimes—you see a 500 error on checkout, but can't reproduce it every time. If you don't document it, the next time another tester sees it, they start from zero. If you document your findings and environment, the second tester picks up where you left off and spots the pattern faster.
| Session 1 (no docs) | Session 2 (with docs) |
|---|---|
| Saw 500 error once at checkout. Tried 5 times, can't reproduce. Gave up. | Read prior report: "500 error appears when cart total > $1000". Tested with $1200 order. Reproduced immediately. Bug triaged in 5 minutes instead of going unknown. |
5 When to Use It / When NOT to Use It
✅ Do it when...
- You find any defect that needs developer attention
- You are logging issues in a bug tracker
- You want to build credibility with your team
- The defect is intermittent or environment-specific
❌ Skip the full report when...
- You are noting a trivial typo in a shared doc
- The fix is immediate and you are making it yourself
- You are in a live pairing session and fix it on the spot
Before you apply this technique, ask:
- Do you have time to write a complete report, or is this a trivial issue?
- Do you have access to the bug tracker and the right credentials?
- Can you reliably reproduce the issue, or is it intermittent?
- Do you have environment details (browser, OS, account) to include?
6 Common Mistakes — Don't Do This
🚫 Vague titles
I used to think: "Login broken" was enough for a title.
Actually: Vague titles get ignored or duplicated. A good title includes the feature, the action, and the failure. "Login fails with Safari when using saved password" tells the developer exactly where to look before they even open the report.
🚫 Missing expected and actual results
I used to think: Stating the bug was enough.
Actually: Developers need to know what you expected and what you got. Without both, they cannot judge severity or confirm a fix. "Expected: error message shown. Actual: silent failure." That contrast is the core of the report.
🚫 Combining multiple bugs
I used to think: One report per page was efficient.
Actually: One bug per report. If the login button is broken AND the forgot-password link is broken, file two reports. Different bugs have different priorities, different owners, and different fixes. Combining them creates tracking chaos.
🚫 Losing findings when documentation systems change
I used to think: I could rely on my verbal handoffs or shared notes.
Actually: When the team migrates bug trackers or documentation systems, findings in notes and memory vanish. Write findings into formal bug reports that transfer with the project.
When this technique fails
Documentation fails when you write so much detail that developers never read it, or when you write vaguely and it's immediately closed as "cannot reproduce". It also fails when you wait too long to document—your memory of the environment and steps fades. Write it down immediately after finding it, while it's fresh.
7 Now You Try — Interview Warm-Up
Scenario: You found a bug: on an NZ retail site, applying the discount code "WINTER20" removes the GST from the total. Write the title and the first three reproduction steps.
Write your answer before revealing the suggested version.
Suggested bug report:
| Field | Content |
|---|---|
| Title | "Discount code WINTER20 removes GST from order total" |
| Step 1 | Add any item to cart and proceed to checkout |
| Step 2 | Enter discount code "WINTER20" and click "Apply" |
| Step 3 | Observe the order total |
| Expected | 20% discount applied; GST still shown and included in total |
| Actual | GST line item disappears; total is 20% below expected value |
Tip: The title names the exact code and the exact failure. The steps are numbered and specific. The expected vs actual contrast makes the bug unambiguous. A developer can reproduce this in two minutes.
8 Self-Check — Can You Actually Do This?
Click each question to reveal the answer. If you got all three, you're ready to practice.
Q1. Why is "Expected result" important in a bug report?
It tells the developer what correct behaviour looks like. Without it, the developer may not know whether the actual result is wrong or whether your expectation is wrong. The contrast between expected and actual is the heart of the report.
Q2. Why should you file one bug per report?
Different bugs have different fixes, priorities, and owners. If you combine them, one bug might be fixed and the other ignored. The closed report looks resolved when it is only half resolved. One bug, one report.
Q3. What makes a good bug report title?
It includes the feature, the action, and the failure. "Continue button unresponsive on Safari after selecting credit card" is good. "Payment broken" is bad. A developer should know where to look from the title alone.