Start with what the person was trying to do
“It doesn't work” can be an accurate bug report. It just leaves a lot for the developer to discover.
Which page was open? What happened before the error? Did the request fail, or did the interface fail to show the result?
The person reporting the problem may have no way to answer that last question. They were trying to finish a task. Asking them to become a debugger before they can ask for help adds work at an already frustrating moment.
That's the problem I'm working on with Shotlog, a React library for reporting problems from inside an application.
Let the application supply the details it knows
The description is the only required part of a Shotlog report. Screenshots and recordings are optional.
That leaves room for the reporter to explain the part the application cannot infer: what they expected to happen.
Alongside that description, Shotlog can include environment details, context supplied by the host application, and a diagnostic trail of recent console warnings, errors and failed network requests. An Included Details preview lets the reporter inspect the accompanying information.
For example, imagine a report that says: “I changed the quantity, but the total stayed the same.” The description gives us the expectation. A screenshot shows the visible result. A failed request nearby gives us somewhere to begin investigating.
Those are different pieces of evidence. None of them proves the cause on its own.
Use a screenshot to point, and a recording to explain a sequence
A screenshot is useful when the problem is a specific thing on the page. An arrow or a circle can remove several sentences of explanation.
Shotlog includes an annotation editor with shapes, text and a pixelation tool for obscuring details in a screenshot.
Some bugs need movement. A menu closes too early. A value briefly changes and then changes back. Something breaks only after navigating between two screens.
For those cases, the reporter can record their tab, narrate what they're doing and draw on the page while demonstrating the problem. A short recording preserves the order of events that a still image cannot show.
Keep video out of the report request
Adding recordings introduces a delivery problem: video is much larger than the rest of the report.
In Shotlog's recording flow, the browser uploads the video directly to storage. The application's support endpoint issues the upload and checks its signed ticket. The resulting report links to the recording.
That keeps the support endpoint from having to relay the video bytes. It also leaves the storage integration replaceable: the recording interface supports providers that use presigned upload URLs.
Decide what belongs in a report
Diagnostic information can contain things a support team should never receive. Screenshots and recordings can expose whatever is visible on the page.
The host application needs to decide who can submit reports and what context to attach. Shotlog provides a server-side authorisation hook, request limits and schema validation. Delivery destinations are configured on the server.
Screenshot pixelation is useful, but it doesn't make every kind of capture safe. A recording needs its own care, particularly when the reporter changes screens during capture.
Send the report where someone will read it
Shotlog can deliver reports through email, Slack or signed webhooks. I've started integrating it into Boca and Uploadfile so reporting sits inside the products themselves.
Once a report arrives, a developer can open the affected screen, follow the recorded sequence and compare the expected result with the visible one. A failed request provides a specific place to investigate without asking the reporter to reconstruct everything that happened.