Skip to content

Explain, Document, & Review Code With Video Messages

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.

Code reviews

We frequently use Loom videos in code reviews. Our Chrome extension expands Loom links inline on GitHub and GitLab so we don’t have to click into the Loom URL. Here’s what this looks like on GitHub:

Loom in GitHub integration screenshot

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.

Engineer Steve Milburn provides a code review for individual and team folder categorization.

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.

Paulius details 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.

Claudio recorded a loom to detail a code pattern review.

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.

Harshyt shares a code overview for feature flagging using Loom.

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. 

Loom web infrastructure README screenshot
This is what a section of our Loom web infrastructure README looks like.

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.

Engineer Luis Ramirez recorded a loom to describe his approach to the file architecture for the Loom for iOS app.

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. 

In this loom, Senior Software Engineer Johnny Opao makes getting the user to send us orphaned video files a bit more friendly and approachable despite the flow being quite complex.

Run postmortems

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.).

A list of factors, solutions and a video overview of what happened and why

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.

In this loom, I lay out that we prioritize system ownership above other technical docs so anyone on our team can find the Engineer who might be responsible for a bug to get more context.

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. 😄

Welcoming Bruno to the team GIF
This GIF shows a Notion doc full of Looms welcoming Bruno to the team.

Report bugs

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.

I outline a bug I found in a candidate’s video recording process.

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.

Loom integrated inline in Slack screenshot
Since our video player expands inline in Slack, our team doesn’t need to click through to the Loom link.

As a side note, you can read about our road to building our feature flagging system.

Common misconceptions

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:

  1. 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.

  2. 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! 😀

Get Loom for your engineering team.


Jul 11, 2022

Featured In:

Share this article: