Field notes, with opinions marked as opinions.

A bug report is not a complaint and not a record for your appraisal. It is a handover. You have a piece of knowledge, “this fails under these conditions”, and you are passing it to someone who was not there. The test of a good report is simple: can the developer reproduce it, form a theory and start fixing without sending you a single question? Every clarifying message you trigger costs a round trip, and in a team spread across Chennai, Pune and a vendor in another time zone, a round trip can cost a day.

The title is read by forty people

The developer reads the whole report. Everyone else reads only the title: the triage meeting, the release manager, the person searching for duplicates. So the title must carry the symptom, the place and, where it helps, the trigger.

Weak: “Payment not working”. Better: “UPI payment shows success screen but order stays Pending when app is backgrounded during approval”. The second one tells you the feature, the observable wrong behaviour and the condition. It is also searchable, which matters when the same defect gets reported twice.

Opinion: never put the cause in the title unless you have proved it. “Database timeout on orders” might be a guess. Describe what you saw.

Steps that a stranger could follow

Write numbered steps, one action each, starting from a known state. Say which account type and which data. “Log in as a user with a saved card and one item in the cart” beats “go to checkout”. Include values that matter: the pin code, the amount, the coupon. If the failure depends on a value like ₹0.50 versus ₹1.00, a step that says “enter an amount” has hidden the bug.

Then two short lines that people skip and should not:

  • Expected: what should have happened, and where you got that from (the requirement, the design, an earlier version).
  • Actual: what did happen, including the exact error text copied, not paraphrased.

Without “expected”, you leave the developer free to say “it is working as designed”, and sometimes they will be right. Naming the source of your expectation closes that argument early and politely.

Environment and evidence

Build number or commit, environment (QA, UAT, staging), browser and version or device model and OS version, app version, date and time with timezone. Time matters more than people think: a developer can search server logs for a two-minute window in IST, but not for “yesterday”.

Attach evidence, but select it. A screen recording of a flow is excellent for a UI problem; a screenshot is fine for a static wrong label. For an API problem, give the request and response with headers, and remove tokens and personal data first. Attach the relevant log lines rather than a 200 MB file, and give the user id or order id so the developer can find the right record. Opinion: a ten-second recording is worth a paragraph of description, but it does not replace the steps.

Do a little narrowing before you file

Five minutes of work can save an hour of the developer’s day. Ask yourself:

  • Does it happen every time, or one in five? Say which, and say how many attempts you made.
  • Is it limited to one browser, one device, one user role, one data set?
  • Did it work in the previous build? If so, name that build: it points straight at a recent change.
  • Is there a simpler way to trigger it, with fewer steps?

Do not overdo it. You are not required to find the root cause, and guessing at it in a confident tone can send the developer down the wrong road. Mark guesses as guesses: “Possibly related to retry logic, not confirmed.”

When it will not reproduce

Some defects appear once and vanish. File them anyway, but be honest in the title: “Intermittent”. Record what you remember was different that time: network switching, a long-idle session, two tabs open, a build deployed minutes earlier. Save logs and the exact timestamp before they rotate. Then, if it comes back, you have a second data point, and two occurrences often reveal a pattern a single one hides. Resist the temptation to close it because you could not repeat it; an unreproduced bug is still a bug that happened.

Tone, severity and the argument you will have

Describe the behaviour of the software, not the competence of the person who wrote it. “The total is wrong” is a fact. “Careless calculation” is an accusation, and it makes the next conversation harder.

State the impact in business terms: “Customers on prepaid orders are charged twice; refund requires manual finance action.” Impact lets the triage group set severity and priority sensibly instead of reading your adjectives. One defect per report, too. A report that says “three things wrong on the profile page” cannot be fixed, verified or closed in parts.

And when a developer replies “works on my machine”, do not take it personally and do not escalate. Treat it as a data problem. Compare build, configuration, data and environment. Offer a call and reproduce it together on a screen share. Nine times out of ten the difference turns up in the first few minutes, and that difference is often the most useful fact in the whole report.

Leave a Reply

Trending