How Video Messages Help Us Explain and Review Code
As Loom’s CTO, I have witnessed how our video messaging tool greatly improves the asynchronous communication and performance of our team as well as those of the engineering leaders I speak with in sales and partnership meetings.
I’d like to share some of these use cases with the hopes that it will help other Engineering teams run more impactful code reviews, document with more context and less ambiguity, and showcase their work in a way that wasn’t possible without the combination of narrative and visual context Loom provides.
Show off how a feature is built
Sometimes we open a code review to build out a feature that the user can see and interact with. It can be difficult to map how the code we’re reviewing relates to the interface and interactions being built. We use Loom to answer the question “How does this code surface to the user?” before any of the code is actually reviewed.
Provide investigative context
When we’re fixing a bug or issue, we’ve found it useful to provide a story that leads to the fix. Often the fix might be simple but the underlying story and pivots in investigation are not, which can lead to issues where code is accepted without full understanding from the reviewer.
Providing full context with video not only helps us better understand a fix, it aids in spreading communal knowledge, making the act of reviewing the code more impactful. Here’s an example where Engineering Manager Paulius Dragunas investigates a memory leak.
Explain how to read a code review
Sometimes our code reviews contain many small fixes that follow a story or many large file additions that follow a substantial feature. Although we try to be good engineers and split up our code reviews as much as possible, this isn’t always practical when trying to meet a deadline or a common goal.
In the Loom video below, Technical Lead Claudio Semeraro introduced many sparse changes that led him to hitting his own quota of test run times. He could have split this up into multiple code reviews, but he wanted to stay heads-down and make sure our tests ran no longer than 2.5 minutes.
Comment on code
Sometimes code is complicated for a good reason, and we use Loom to document instances of this and provide context.
In this example, Engineer Harshyt Goel introduced many large changes because our feature flagging infrastructure includes many disparate pieces working together in a pipeline. To make a deadline, it was easier to put it all together in a single PR and include tests.
Documentation and onboarding
Show how to set up a repository
A common issue we face when we hop into a new code repository is how to set it up and get to contributing as fast as possible. Although text instructions are great for quick digestibility, providing a video helps us explain what top-level setup commands do and how you can debug common package installation errors.
Explain architecture diagrams
We love using architecture diagrams to document the flow of information through our systems.
What we’ve found is that, by providing a loom, we can cut down the amount of time it takes someone to onboard to a new system.
Instead of spending meetings rehashing how an architecture works and how to read the diagrams in our wiki, with Loom videos, new engineers are able to read the diagram, get an overarching story of why we landed on this implementation, and then come into an onboarding meeting with questions that go a level deeper than initial understanding from written copy alone. This has been a huge time saver for our team.
Detail debug flows
Often there are repeatable steps either a user, a support member, or another engineer can take to help us debug what’s going wrong. These steps can be laid out over text, but context can go missing and cut-and-dry instructions can seem daunting, especially the more complex the debug flow gets.
Postmortems help us understand what’s gone wrong in the past, where things might go wrong in the future, and how we can evolve our processes to be a better Engineering team. Often, if a given part of our infrastructure fails under the load, we look at previous postmortems to help us get up to speed as to why things might be breaking.
Bulleted insights are best, but the resolution of the full story is lost, and, as hard as we might try, we often can’t remember every detail if the previous issue surfaced far enough back. That’s where we leverage Loom to provide a full breakdown of what was going on across the board (charts, conversations in Slack, pivots in investigation, etc.).
Helping others navigate complicated wiki pages
Sometimes the layout of a wiki page itself can be complicated. This is an admittedly meta use case, but we have videos introducing folks to top-level documentation so they know how to navigate to the information that they might be most interested in.
Record welcome videos
We’re on a mission to enhance workplace communication and bring back its humanity. The human part is really important to us, and since we often can’t physically meet our new remote teammates on their first day, we send them welcome videos letting them know why we’re excited for them to hop on board. This use case isn’t specific to engineering. 😄
Sometimes we need extra context for a bug report to understand why it might be happening and how to reproduce it. Although text is great, it can take a while to write up and we’ve often found that we lose clarity when we map what we’re seeing and experiencing to text.
This loss of information in translation from experience to text can happen for many reasons: Our support team might use different nomenclature for various parts of our product, the issue might be a UX bug instead of an actual code bug, etc.
We’ve found that Loom helps drastically reduce time-to-fix for bugs reported from both engineers and non-technical teammates.
Showcase new features
Our team relies on feature flagging and doesn’t follow a standard release cadence to production. This means we can release new and updated features to production that only our team sees, a percentage of our audience sees, or just the Engineer working on the feature sees. We have a #release-notes Slack channel filled with notes about these features as well as videos going over how the feature will surface.
Because Loom is creating a new type of workplace communication, I’ve heard many misconceptions about how and when it should be used, so I’d like to close by dispelling some of those:
Some people assume Loom is trying to replace all text-based communication. This is simply not the case. Loom is not an all-or-nothing tool — some of its best use cases are to complement other information, especially when it’s complex and visual in nature.
People who have had exposure to Loom in the past may believe the tool is best used for one form of communication — either internal (most of the use cases here) or external (sales prospecting, marketing campaigns, customer support showing people how to debug something, etc.). We are on a mission to enhance all workplace communication. Loom is an intentionally horizontal use case tool because we believe we’re in a unique position to effectively service many workflows, both internal and external, with video.
If you and your team come up with new use cases for Loom that help you be better at your job, I’d love to hear them! Send me a tweet @vhmth or email me at firstname.lastname@example.org! 😀
Get Loom for your engineering team.
Get expert workplace communication tips delivered straight to your inbox.
Written by Vinay Hiremath
Vinay is Co-founder and CTO of Loom.