A developer investigating a failed export needs a starting point: the account, the saved record and the action that triggered it. The bug report supplies that context and the evidence needed to investigate. Your task is to describe the failure accurately; diagnosing its cause comes later.
Describe the failure and how to reach it
Give the report a title that names the feature and visible symptom. Separate what you expected from what actually happened, using documentation or an agreed requirement to explain the expectation. Treat details such as account permissions as starting conditions, and label any suggested cause as a hypothesis.
For colleagues using English as an additional language, resources such as Business English for IT provide practice in discussing technical problems. In the report itself, preserve exact button labels and error messages so readers can recognise the same behaviour.
Capture the relevant setup before changing settings or restarting the application. Depending on the problem, that could include the application version, browser, operating system, account permissions and data being used.
Write numbered steps from a clearly defined starting state. Include the selections needed to reach the problem, ending with the triggering action, then record the result separately.
Use the shortest sequence you have actually tested. If you remove an apparently unnecessary step, check the revised sequence: that step might contain the condition that makes the failure happen.
A worked bug report you can adapt
This hypothetical report provides a structure you can adapt to your own application.
Title: CSV rota export displays “Export unavailable” for a manager account.
Environment: Rota application, test build 4.2; Firefox 140 on Windows 11; staging environment.
Preconditions: Signed in with a manager test account assigned to North team. A published sample rota named “Next week” is available and contains synthetic staff data. The account has export permission according to the permissions screen.
Steps to reproduce:
1. Open Rotas from the main navigation.
2. Select North team.
3. Open the saved rota named Next week.
4. Select Export, then CSV.
Expected result: A CSV file downloads containing the shifts shown in the selected rota, as described in the application’s export help page.
Actual result: The message “Export unavailable” appears above the rota. No download starts, and the rota remains visible.
Frequency: Two failures in five attempts using the same account and saved rota. Other browsers and account roles have not been tested.
Impact and workaround: Failed attempts prevent the manager from exporting shifts for spreadsheet reconciliation. Copying the displayed rows into a spreadsheet worked as a temporary alternative.
Evidence: Screen recording of the second failed attempt using synthetic data, plus a screenshot showing the application build. The recording is labelled with the event time and time zone. No diagnostic logs were captured.
When the failure is intermittent
An intermittent failure is still worth reporting. Record its frequency and timing, keeping conclusions limited to the conditions you tested.
Compare successful and unsuccessful attempts. Note any differences in the affected record, network connection or how long the application had been idle.
Stop testing if repeated actions could duplicate transactions or damage data. Preserve the evidence already available and explain why testing stopped.
Check impact and evidence before submitting
Describe the consequence rather than simply marking everything urgent. Can users continue through another route? Is work blocked, or is the problem an inconvenience? Severity concerns impact; priority concerns when the team should address the issue. Follow the receiving team’s definitions where those fields are required.
Review attachments for personal information, passwords, access tokens and confidential business data. Remove unnecessary sensitive content and use an approved restricted channel for evidence that needs limited access. A recording should capture the relevant sequence, rather than an entire desktop session.
Search for an existing report and follow the project’s submission instructions. Add evidence to a matching issue instead of creating a duplicate. Keep separate problems in separate reports unless their connection has been established.
Before submitting, read the steps as someone who has never seen the failure. Can they find the right starting screen, carry out each action and recognise the result?