“Illustrations in a picture book help children understand what they are reading, allowing new readers to analyze the story. If children are having difficulty with the words, the illustrations can help them figure out the narrative, which can increase their comprehension.” (EBSCO, "Seeing is Believing")
This idea of illustrations being an important piece of a much larger storytelling puzzle is a great parallel to how organizations optimally like to digest bug reports. Sure, engineers can go back through the logs and observe the stack-trace. Or maybe they are lucky enough to receive some steps to reproduce (link to other article). But what if the story they get still feels foreign?
An issue when it happens is an expression of many parts of the system working together, and our job as debuggers can be likened to that of storytellers, reconstructing a past story with little bits of context we pieced together. Great storytellers can create a scene and make it feel almost like we can see it.
Let’s talk about visuals.
A picture is worth a thousand words. Well, in this case, words can actually have a ton of value, but often the visual attached to the associated action really rounds out a story. What did the user’s screen look like when the issue happened? How about leading up to the issue? Is there something I can’t see in the trace that gives me a clue?
In addition to the practical value of using graphics to provide context to actions, they also help build empathy for the user. They connect the technical story to the visual so we understand what the user wanted to do, and why it felt off.
In the engineering world, videos and screenshots can help provide a quick look into what the application looked like in a specific moment, but there still remains a certain amount of depth that is left unaddressed at times. What was happening on the other part of the page at that moment that can help better inform what went wrong? Am I able to click into the experience, identify classes and structure to quickly understand the construction of the application? Even a full video of a user session can lack crucial details for understanding what’s causing a bug.
Capturing visual context
With this in mind, we have built DOM snapshots to accompany each step in the user’s journey. We believe this will serve as a cross functional way to provide value to different people within the organization, by creating assets that speak to everyone in the organization. More specifically, we do that by...
- Capturing a full page shot at the exact moment an action was committed.
- Expanding inspectable elements
- Demonstrating cursor movements
- Highlighting features in question
- Positioning each snapshot so you can flip through and create a more succinct visual journey
With DOM snapshots, you can visually walk through the journey with DevTools open side-by-side. You can see the network failing right after the user clicked on that button two times in a row. You can see what your user saw, and see what was happening under the hood as well.
Fitting value into your workflow
As we searched for the best way to integrate snapshots into a report, we found that forcing the snapshot-location behavior was a sure way to frustrate our users. Engineers are unique in that we all work within a specific mental framework, so we prioritized optionality for accessing contextual visuals. With that in mind, we built out the following access points for snapshots in PlayerZero reports:.
Hover on the step for quick access to the Snapshot
For an easier, more practical way to understand the high level user journey outlined in the steps section.
Add a DOM Snapshot and repro step link directly in the Activity Feed
For tethering comments or deeper insights to a step with more vibrance.
Dive deeper by clicking into the step for an expanded view
For a more engaged page viewing experience.
DOM Snapshots provide pixel-perfect renders of the page, and also enable huge performance benefits, making the data collection, storage, and sharing experience much snappier.
We asked ourselves: How can we best position the users of the PlayerZero bug reports to succeed in building empathy and understanding for the user’s experience?
We want to allow EVERYONE to be a part of the debugging process. DOM snapshots are the great connector, they allow non-technical team members to get a feel for the experience, while also providing the technical depth necessary for developers to present value.