Case Studies →
Engineering

How quick videos help us explain and review code

Loom's Head of Engineering shares how he and his team leverage quick videos in code reviews, documentation, onboarding, and many other areas - greatly improving the communication and performance of Loom's engineering organization.

As Loom’s Head of Engineering, I have witnessed our tool leveraged in ways that have greatly improved the communication and performance of our team as well as those of the engineering leaders I’ve been speaking within 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 Loom.

Code reviews

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

Showing off the feature being built

Sometimes the code review we open is 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. “How does this code surface to the user?” is a question we use Loom to help us answer before any of the code is actually reviewed.

Providing investigative context

When we’re fixing a bug or issue, we’ve found it useful to provide a story that lead to the fix. Often times 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 not only helps us understand a fix better, it aids in spreading tribal knowledge, making the act of reviewing the code more impactful. Here’s an example where Paulius is investigating a memory leak.

Explaining 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 this example, Claudio introduced many sparse changes that lead 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.

In this example, Harsh introduced many large changes because our feature flagging infrastructure includes many disparate pieces working together in a pipeline and he had to hit a deadline so it was easier to put it all together in a single PR and include tests.

Code comments

Sometimes code is complicated for a good reason, and we use Loom to document instances of this and provide context.

Documentation & Onboarding

How to setup 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 has helped us explain what top-level setup commands do and how you can debug common package installation errors. This is what a section of our Loom web infrastructure README looks like.

Explaining 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, new engineers are able to read the diagram, get an overarching story of why we landed on this implementation, and then come into an on-boarding meeting with ready set questions that go a level deeper than initial understanding. This has been a huge time saver for our team.

Detailing debug flows

Many times there are repeatable steps either a user, 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 can get. Here’s an example where Johnny makes getting the user to send us orphaned video files a bit more friendly and approachable despite the flow being quite complex.

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 load, we look at previous postmortems to help get us 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 help 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. Here’s an example from our engineering wiki where I lay out that we actually prioritize system ownership above other technical docs so anyone on our team can first find the engineer who might be responsible for a bug to get more context.

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

Bug reporting

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

Showcasing new features

Our team relies on feature flagging and does not follow a standard release cadence to production. This means we can release new/updated features to production only our team sees, a percentage of our audience sees, or just the engineer working on the feature. We have a #release-notes Slack channel filled with notes about these features as well as videos going over how the feature will surface. Since our video player expands inline in Slack, our team doesn’t need to click through to the Loom link.

As a side note, if you’d like to read about our road to building our feature flagging system, you can read about that here.

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 this article out 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.). Loom is on a mission to enhance all workplace communication. We are intentionally a horizontal use case tool and believe we are in a unique position to effectively service many workflows, both internal and external.

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 vinay@loom.com! :-)

More Use Cases

See how Loom is helping teams communicate effectively and stay aligned

Video recording,
simplified.

A new kind of work communication tool that helps you get your message across through instantly shareable video.

Get Loom for Free