A bug report has one job: let somebody who was not there reproduce, or at least believe, what you saw. Everything below serves that job. Nothing below is bureaucracy.
The short version
- What you expected to happen.
- What happened instead, literally, including "nothing".
- How to get there, starting from a state a stranger can reach.
- How often, and since when.
- What you already ruled out.
If you write nothing else, write the first two. They are the pair that separates a defect from a misunderstanding, and they are the pair most often missing.
What you expected
This is the part people skip because it feels obvious. It is not obvious to the reader, and it is the only part of the report that reveals what you were trying to do.
A meaningful share of bug reports turn out to be disagreements about intended behaviour rather than faults. Stating your expectation is what surfaces that on day one instead of week three.
The export is broken.
I expected the CSV to contain every row shown in the table, about 4,300.
What happened instead
Be literal. "It failed" covers at least eight distinct outcomes: an error message, a silent no-op, a spinner that never resolved, a partial result, a result that looked fine and was wrong, and several more. They are different defects.
If there was an error message, paste the text. Not a screenshot of the text, if you can avoid it, because the text is searchable and the screenshot is not. If there was no error, say so explicitly: "no error, no warning" is a genuine finding and tells the reader the software did not know it had failed.
How to get there
Steps should start from somewhere the reader can also start. The most common failure in bug reports is steps that begin halfway through, from a state you had built up without noticing.
Test each step against a stranger: could somebody who has never seen your setup do this? "Open the report you made earlier" fails. "Reports, then All Activity" passes.
Name concrete data. "A large file" is not a fact; "a 4,300 row report" is, and the number may turn out to be the whole bug.
How often, and since when
Two short answers that decide how the ticket is handled.
How often distinguishes "every time" from "once, and I moved on". Both are worth reporting. Only one of them is worth someone else's afternoon trying to reproduce. If you tried three times, say three times.
Since when is the highest-value sentence in most reports. If it worked last week and does not work now, the search collapses to what changed in between. If it has never worked, you may be looking at a feature that does not exist rather than one that broke.
What you already ruled out
Almost everybody tries something before filing. They refresh, they try another browser, they ask a colleague whether it happens to them too. Almost nobody writes it down, so the next person repeats it.
One line is enough: "Happens in Safari and Chrome, and to two colleagues as well."
When you cannot reproduce it
Unreproducible reports are still worth filing, but they need different content. Substitute:
- A timestamp, even approximate. It converts the report into a log search, which is frequently better than reproduction.
- An identifier: the account, the record, the request ID if one was shown.
- What was unusual: first time using it, unusually large input, just after an update, poor connection.
Those three turn "cannot reproduce" into "can investigate".
What not to bother with
Your diagnosis, presented as the problem. "The cache is broken" hides what you saw behind a guess. Say what you observed, then add the guess separately if you have one. It is often useful, just not as a substitute.
Severity, unless you know how it is used. Most teams re-triage it anyway, and an inflated severity costs you credibility on the next report.
Apologising for the report. "Sorry, this is probably my fault" makes readers discount it. If it turns out to be user error, that is still a finding: something was confusing enough to look broken.
A complete example
Expected the CSV export from Reports, All Activity to contain all 4,300 rows shown on screen. Got a file with exactly 1,000 rows, no error and no warning. Reproduced three times from a fresh login on the QA account with the range set to 1 May to 29 July; it worked on 14 July when I ran the same report. Happens in Safari and Chrome, and to two colleagues on the finance team.
That report is not longer because its author tried harder. It is longer because somebody asked the five questions, and every answer was already in their head when they sat down to file.