Guide · Video & communication
Record a Bug Report a Developer Can Use
Show the steps, the failure, and the expected result in a short recording, then include the details that video cannot reliably carry.
"The form is broken" gives a developer a place to start guessing. A useful bug recording shows a repeatable path to the failure and explains what you expected instead. You can often record that in less time than it takes to write a long message about how frustrating the problem feels.
Prepare the example before recording
Choose a test account and remove unrelated personal or customer information from the screen. Close tabs that don't help explain the issue. If a notification, password manager, or browser history could appear, deal with it before you start sharing the screen.
Try the steps once. Note whether the problem happens consistently or only under a particular condition. A recording of an intermittent failure is still useful, but say that it's intermittent. Don't edit several attempts together in a way that makes them look like one continuous reproduction.
Show the state before the click
Start where the viewer can understand the conditions. If a form fails only after an attachment is added, show the attachment step. If the error depends on a particular user role, include that role in the accompanying report without exposing credentials.
Narrate the actions that matter. "I selected the existing customer, added a PDF, and clicked Save once" is more useful than a fast cursor moving through several screens. Pause at the failure long enough for the viewer to read it. If an error disappears quickly, include its exact text in your notes.
Explain the difference you observed
For a hypothetical intake form, a report might say: "I expected one saved request with its attachment. The confirmation appeared, but the request list stayed empty after refresh." That separates the observed behavior from your theory about the cause.
It's fine to offer a hypothesis, but label it. "This might be related to attachments because the same steps work without one" gives the developer a lead. "The database is broken" makes a much broader claim that the recording probably doesn't establish.
Add the details beside the video
The recording should be supported by a short written report. Some information is easier to copy, search, and compare as text. Give the team a title that describes the failure and the conditions, then add the essentials.
Use the team's approved place for sensitive diagnostics. A public video link isn't the right container for access tokens, private customer records, or a raw log full of personal information.
- The page or feature, browser, device, and relevant account role.
- The exact sequence of steps and any required starting state.
- Expected behavior and actual behavior, in separate sentences.
- The time of the attempt and the exact error text, if available.
- Whether you could repeat it and whether a simpler case worked.
Test the fix with the same example
When the fix is ready, repeat the original steps using the same relevant conditions. Then try the nearby case that previously worked. If you change the browser, role, input file, and workflow all at once, you may prove only that a different scenario works.
Keep the report and verification together. The next person who sees a similar failure can compare the two instead of starting from an empty description and another round of questions.