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 Revenue NZ 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.
Senior engineer insight
The single thing that changed how I think about bug reports: a developer's time is worth five times a tester's time in most NZ teams. A vague report that forces a dev to chase you down for browser version, account state, and reproduction steps is not a minor inconvenience — it's a budget problem. Once I started treating every report as a document that had to stand alone at 2am when I wasn't available, my reports got dramatically sharper inside a week.
The most common mistake Grad testers make: writing the title last, after they've already forgotten the specific failure mode they observed — resulting in a generic title that matches a dozen other tickets in Jira.
From the field
On a government payments project in Wellington, the team assumed that testers and developers shared an understanding of "what broken looks like" — so bug reports were light on expected results. When a new developer joined mid-sprint, she was assigned three Jira tickets that each said something like "form submission fails intermittently." With no expected result documented, she had no baseline to test against, and all three tickets bounced back to QA as "cannot reproduce." The team lost a full sprint cycle untangling it. After that, the BA mandated that every defect ticket include an explicit expected result as a Jira field — not optional prose. The lesson: expected result is not for the developer who wrote the feature; it's for the developer who didn't.
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 Revenue NZ payment issue. Follow these steps every time you find a defect.
Scenario: You are testing the Revenue NZ payment portal. After entering a valid Revenue NZ 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 Revenue NZ 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 Revenue NZ 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 Revenue NZ 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.
Why teams fail here
- Testers write reports immediately after finding the bug but skip environment details, assuming "everyone knows we're on Chrome" — then the bug turns out to be Safari-only and the report is useless.
- Jira tickets get filed with a vague title copied from a Slack message, then never updated — the formal report and the actual defect drift apart as the conversation moves on.
- Junior testers bundle two or three related failures into one ticket to save time, which causes the ticket to get closed when the first failure is fixed — leaving the others untracked and silently shipped.
- Government and enterprise projects in NZ often involve systems with complex preconditions (specific account types, tax years, login roles) — when testers omit preconditions, developers test against the wrong state and cannot reproduce the defect at all.
Key takeaway
A bug report is not a note to yourself — it is a formal handover document, and the moment you file it you will not be in the room to explain it.
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.
Interview Questions
What NZ hiring managers ask about Write It Down at the Grad level.
Q1. What should a bug report contain, and why does each element matter?
Strong answer: Title (summarises the problem), steps to reproduce (exact, numbered, from a known starting state), actual result (what happened), expected result (what should have happened), environment (browser, OS, app version), severity (impact on users), and evidence (screenshot, recording, network log). Each element serves a purpose: the title helps triage; steps let developers reproduce it; actual vs expected defines the bug; environment identifies whether it is platform-specific; severity guides prioritisation; evidence proves it is real and accelerates the fix.
Q2. A developer cannot reproduce a bug you found. How do you approach this?
Strong answer: I walk them through my reproduction steps in real time, on my machine if possible. I check whether I noted the exact environment details (browser version, OS, account type used, data state). I try to reproduce it again from scratch following my documented steps. If I cannot reproduce it, I note whether it was a one-off or if I saw it multiple times. Intermittent bugs are real bugs — I document the frequency ("seen 3 times in 30 minutes"), even if I cannot guarantee reproduction. A screenshot or recording from the original occurrence is invaluable here.
Q3. Why is it important to document your testing, even when everything passes?
Strong answer: Test documentation is evidence that testing occurred — required for audit trails, regulatory compliance, and knowledge transfer. When a production incident occurs months later, documentation answers "what was tested before this went live?" Test notes record what was covered, what assumptions were made, and what was deprioritised — providing context that is otherwise lost when the tester moves on. For NZ government projects with gateway reviews, documented test evidence is a sign-off requirement, not optional. Passing tests are not less important to document than failing ones.
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.