The three sentences that matter

What you did, what you expected, and what happened instead. Almost every unusable bug report is missing at least one of these, and almost every good one leads with all three.

"The export is broken" contains none of them. "I clicked Export on the March report, expected a CSV download, and got a page saying Something went wrong" contains all three and is immediately actionable.

Make it reproducible

List the steps precisely enough that someone unfamiliar with the feature can follow them. Include the starting state — which account, which data, which page.

If it happens only sometimes, say so and say how often. An intermittent bug is investigated completely differently from a consistent one, and mislabelling it wastes days.

Include the context

The exact time it occurred, the account or user, the browser or device, and the environment. These let an engineer find the request in the logs, which is frequently the difference between a ten-minute diagnosis and a two-day one.

A screenshot or a screen recording is worth a great deal, particularly for anything visual or intermittent.

One problem per report

Batching several issues into one report means it cannot be closed until all are fixed, its status becomes ambiguous, and the smaller ones get lost.

Separate reports can be prioritised independently, which is usually what you actually want.

Say what it is blocking

Impact drives priority far more than severity language does. "This blocks month-end for the finance team, who cannot close until Friday" is more useful than marking something Critical.

Be honest about it. Teams that mark everything urgent lose the ability to signal when something genuinely is.

Do not include secrets

Screenshots and log extracts routinely contain session tokens, API keys, and personal data. Redact before attaching, and never paste a real password into a ticket that will be visible to everyone with access to the tracker.

Written by the Global IT Solutions engineering team. Working through this decision right now?

Start a conversation