#100 – Why documentation is important for our engineering team (Ben Grynol, Maxine Whitely, Steph Coates, & Ian Schumann)

Creating consistent and cohesive documentation is key for the Levels engineering team. But that’s easier said than done. Levels Head of Growth, Ben Grynol, sat down with our software engineers, Maxine Whitely, Steph Coates, and Ian Schumann to break down their approach to documentation. They talked about why it matters for an asynchronous remote team, how it mirrors building healthy habits and why it’s worth it to invest in documentation now versus paying the price of not having it later.

02:54 – The parable of the engineer

Ian said that the parable of the engineer demonstrates the importance of documenting your thought process for future reference.

There’s a simple parable about a day in the life of an engineer, that I think lends well to documentation and also just writing good quality code. It’s real short. So, some engineer is moving along through the code base, trying to add feature functionality to existing code, and in order to do this, for the non-engineers out there, it’s really important to understand how the existing code works before you go tampering with it and changing it, right? So, engineering looks into the stuff that’s already there, the stuff that’s already been written, and living and functioning in the code base for a year or more. They said to themselves, “What idiot wrote this? This doesn’t make any sense. It’s totally unreadable. The things are named weirdly. There’s no inline documentation.” That’s the segue for the topic. So they go back into version control history, and they find out that the idiot who wrote it was them, a year ago. It’s not just really an exaggerated story. This happens, this happens all the time. It happens on every engineering team eventually, sooner or later. You were in a hurry in the first place, you weren’t thinking about the future, you were just thinking about shipping the thing, and so you wrote whatever you wrote in a way that worked well enough. Then, no one touched it for 12 months, and now nobody knows how the thing works, including you, who wrote it originally. So this is the parable, I think, that lays the groundwork for documentation.

05:03 – A bridge to non-technical stakeholders

Maxine said documentation connects technical engineers with non-technical stakeholders to communicate the essence of the product.

For engineers, if there are external stakeholders outside of the engineering organization, we engineers might share a language. We’re all writing code in the same language, whatever it might be. But the folks that we’re working with, external stakeholders, don’t speak that language. So it’s almost like creating documentation is a bridge between technical work and whatever the business outcome is, as well.

09:30 – Having the time to document

Steph said that engineers at Levels are given time and authority to document their processes and reasoning as an equally important part of their responsibilities.

Something that I really appreciate about Levels is, because it’s an engineering-led culture. I do feel, I don’t know if, “empowered,” is the right word, but I do feel like I’m given adequate time to do both, to both write the feature and to document it. I felt, at other companies, where there’s such these strict timelines, by people that may not understand all the things that need to go into fully shipping a feature, that they say, “Oh, well, this should only take two days, or three days.” So, you’ve got to ship it and then documentation becomes an afterthought, and we don’t have the time to do so. So, with Levels, being given the trust to say, “Okay, I’m going to write this, but I need enough time to also document it, to record the, Loom, to write the docs,” that feels really great.

10:12 – Understanding through teaching

Steph said that you can absorb and understand your own work better by documenting it for the rest of the team.

I think being able to summarize what I just did, of writing a feature and then talk through it, to benefit other engineers, it’s that mentality of, you understand something so much more after you teach it to others. So, being able to write a feature and then verbally talk through it, I understand what I did so much more. So, that’s such a hugely beneficial part, is this closeout review to shipping the feature, and before I even put up the PR, I might notice, just through talking or the code and recording myself doing it, I might notice little bugs already, or things that I want to fine-tune. So it benefits me, in that way, of doing this full circle, closed-loop of building the feature.

13:06 – A culture of documentation

Steph said it’s easier to participate in constant documentation when the behavior from the rest of the team already exists.

I think the reason it’s been so successful with that is not because we have this line in some memo that says, “Oh, engineers document things.” But for me, it’s been successful because I’ve seen it modeled by other engineers at the company, of, “I joined, and I saw Justin recording Looms, and I saw Xinlu writing up a notion doc about how she re-architected the user feed,” and being able to see it done by other people automatically instills that in you, of, “I want to behave the same way.” So yes, seeing it modeled by the rest of the engineering team, I think, is just an easy way to adjust into that same culture, rather than it just being this bullet point on some notion doc or memo, where we may be saying it, but we’re not living it. But in reality, at Levels, we really are living it, and it’s so easy to assimilate into that culture when it already exists.

20:00 – Avoid documentation debt

Maxine said that consistent documentation is a great solution for avoiding technical debt since it provides clues and context for the rest of the team to move quickly.

When you think about things like technical debt, which folks talk about a lot when you’re trying to build quickly, so you build something maybe in the not most optimal way as a way to ship it, a good way to mitigate technical debt is to avoid documentation debt. So, acknowledging inline, in the code, “This was done weirdly. I know that, here’s why, and here’s how to make it work.” Then, sure, it’s technical debt, but the piece is in place, and the next person who needs to debug it or improve it already has the context to then make that happen so much more quickly.

20:34 – Pay now or pay later

Steph said everything has a price and paying for time to document in the short-term could save lots of time and energy of having to pay for your lack of documentation in the future.

I think we were actually to talking about this in Denver when we were walking around, but in my mind you have to pay a price for something, either now or later, and in the sense of documentation and tech debt, velocity, and speed, and scrappiness is the short-term gratification, I guess, to be like, “Oh, we’re going to release this really quickly,” but you may end up paying for it in the long-term if you don’t take those little steps to document those things, and make sure that the foundation is built well.

23:49 – Don’t make assumptions

Ian said documentation helps mitigate assumptions about code written before you.

It’s very easy to make the mistake of looking at anything that has been written before you that seems to be working and assume, therefore, that it was written correctly, that the author thought it was perfectly well-designed, and everyone is happy with how it’s working today. That is nothing but a confusion, a status quo bias. The reality is, if you go back and look at anything that has been long-standing in a codebase, or even anything that was written recently, there were compromises that were made at the time that it was shipped, and the author or the authors know that. So, when you drop little hints, either into the code base directly or into documentation that’s outside the code base, you give the next person a sense of what is safe to tamper with, and what still is a work in progress. It may be working today, but it really still needs some TLC, if it’s going to go the long haul. Informing the future generations of devs about that is crucial, and that, to me, I think that’s another win from documentation.

26:10 – Bottlenecks without documentation

Steph said the old-school in-person model of tapping someone on the shoulder with every question is not scalable or efficient, especially when something urgent happens.

Something that I will never forget is, the first company that I worked at was a large corporate finance company, and very much an in-person culture, very much a, you join and your onboarding is literally just flailing around for the first six months until you’re immersed enough to fully understand what’s going on. I know a lot of big companies function like that, because there isn’t a big emphasis put on documentation and it’s this mentality of, “Oh, I can just tap this person on the shoulder and get an answer.” But, like you had said, Maxine, that’s not scalable. That’s not automating it. That person has to context-switch every time that you do ask them a question, and something that’s burned into my memory, and I think why I feel really passionate about remote work in documentation now is, I worked in the office and I was really gung-ho about remote work. I wanted to travel, I wanted to live elsewhere. I asked my boss, I said, “Is there any feasibility,” this is way before COVID, “that we would eventually have some sort of hybrid model, or I could be remote on this team?” He said, “Absolutely not.” I asked him why, and he gave an example of, the one infrastructure engineer on our team was so crucial in terms of outages and bugs, and it was the worst-case scenario bus situation, where if he got hit by a bus, the company would fall apart because he was that integral to making sure things worked day-to-day. My boss said, “Well, if everyone goes remote, I can’t tap so and so on the shoulder to ask him when there’s an urgent problem.” That just speaks to this problematic culture around needing people in person, and needing this immediate answer to distract someone from being able to do deep work, because we don’t have our stuff together in terms of things being well-documented, so you have to rely on this one person to be the bottleneck whenever stuff hits the fan.

37:47 – Curate your work for your team

Maxine said that documentation is a process of making your work easier for your teammates and colleagues to follow.

It sounds a lot of what we’ve been talking about, it seems like curating the experience of other people experiencing your work. How can you make it as easy as possible and create this guided journey through your own work? For yourself, for other people. I think that’s a lot of what the best teammates I’ve had do, where they have this amazing way of externalizing their thoughts, and their work, and their progress, so you’re always in lockstep with them. The cohesion is built into the way that they structure working on the problem, and it seems like good documentation is such a key component of that. It’s like the thing that keeps the good process on its rails or keeps the curation moving forward if that makes sense.

Maxine Whitely (00:06):

When you think about things like technical debt, which folks talk about a lot when you’re trying to build quickly, so you build something maybe in the not most optimal way, as a way to ship it, a good way to mitigate technical debt is to avoid documentation debt. So, acknowledging in line, in the code, “This was done weirdly, I know that, here’s why and here’s how to make it work.” Then, sure, it’s technical debt, but the piece is in place, and the next person who needs to debug it or improve it already has the context to then make that happen so much more quickly.

Ben Grynol (00:45):

I’m Ben Grynol, part of the early startup team here at, LEVELS. We’re building tech that helps people to understand their metabolic health, and this is your front row seat to everything we do. This is a whole new level.

Ben Grynol (01:00):

We talk a lot about documentation, this idea of ensuring that all information is not only visible to a team, but accurate, easy to find a path for it, and held in a place where everybody really can find that path. Well, from an engineering perspective, documentation is one of those things that, time and time again, you hear about companies saying, “Oh, go to that person. They are the key holder. They have all the tribal knowledge of why some update was made, or how some code was shipped at one time.” This is a slippery slope and a dangerous path to be on from, an [eng 00:01:46] perspective, if you have an outage and everybody scrambles, everybody tries to figure out what exactly caused the outage. “Go talk to Billy. Billy knows. Billy shipped the code four and a half years ago.” Pretty typical case that you hear.

Ben Grynol (02:00):

Well, from an eng perspective, we focus a ton on documentation. We’ve been doing things of course, in a, LEVELS fashion, a non-traditional way of ensuring that we can iterate on this documentation. How can we make it useful for engineers? How can we make it easy for new engineers to join the team, and get ramped up, and not only immersed in this culture, but really onboarded and ramped up as far as understanding how the code base and how all the previous documentation has come together? Why certain decisions were made? So, Maxine Whitely, Steph Coates, and Ian Schumann, three of the engineers on our team, and myself, sat down and we went through all these different ideas of how engineers can use documentation to benefit the entire team, and how they can keep making things better for each other. It was an awesome conversation, and really fun to dig into, being an outsider in the eng world.

Ben Grynol (02:51):

Well, anyway, here’s where we kick things off.

Ian Schumann (02:54):

There’s a simple parable about a day in the life of an engineer, that I think lends well to documentation, and also just writing good quality code. It’s real short. So, some engineer is moving along through the code base, trying to add feature functionality to existing code, and in order to do this, for the non-engineers out there, it’s really important to understand how the existing code works before you go tampering with it and changing it, right? So, engineering looks into the stuff that’s already there, the stuff that’s already been written, and living and functioning in the code base for a year or more. They said to themselves, “What idiot wrote this? This doesn’t make any sense. It’s totally unreadable. The things are named weirdly. There’s no inline documentation.” That’s the segue for the topic. So they go back into version control history, and they find out that the idiot who wrote it was them, a year ago.

Ian Schumann (03:58):

It’s not just really an exaggerated story. This happens, this happens all the time. It happens on every engineering team eventually, sooner or later. You were in a hurry in the first place, you weren’t thinking about the future, you were just thinking about shipping the thing, and so you wrote whatever you wrote in a way that worked, well enough. Then, no-one touched it for 12 months, and now nobody knows how the thing works, including you, who wrote it originally. So this is the parable, I think, that lays the groundwork for documentation. Code can, only in the best of circumstances, be self-documenting. That’s an ideal that some engineers believe in. Personally, I don’t. I don’t think that code interprets itself for humans, but in most circumstances, I think that code is difficult to read, and engineers, spend more time reading code than they spend writing code. So, leaving documentation is a gift to posterity, your future self, as well as the next developer, the next unfortunate bystander who wanders in, to say, “By the way, here’s how this mess works that I just wrote here.”

Maxine Whitely (04:58):

That’s a great summary. I also think the value of documentation has to do you with when you, for engineers, if there are external stakeholders outside of the engineering organization, we engineers might share a language. We’re all writing code in the same language, whatever it might be. But the folks that we’re working with, external stakeholders, don’t speak that language. So it’s almost like creating documentation is a bridge between technical work and whatever the business outcome is, as well.

Ben Grynol (05:27):

Not to jump too far ahead, but let’s jump into this scenario of, a company goes from zero to one, and eventually goes down a path where there’s some liquidity event. They get acquired by another company. Well, that isn’t like, “Hey, we’re just going to buy this company.” There’s this huge amount of DD that goes into it, and from a tech perspective, people are looking at your stack. They’re looking at all different things, when they can look under the hood and actually get into the code base and say, “What exists here?” The more documentation you have, it makes everything more valuable, because it builds trust. It builds assurance that things are done well. It reinforces that everything isn’t just as much, as startups are, duct tape and Popsicle sticks, everything’s not just bolted and glued together in this weird way.

Ben Grynol (06:21):

So, this idea of building cohesion from the ground up, it can help from a long-term perspective, not just for company execution, but also from a value perspective, where it becomes a point of leverage, where if things are documented really well, it’s like, “Look, this company is clean. They’re set up for success.” There’s going to be a much easier integration than saying, “We’re buying this thing. We don’t really know what it is or what it does, but hopefully we can create some value in the future from it.” There is a state where it’s not just about setting up the next person for success and saying, “Hey, we’re going to make things easier and faster,” because you want to maximize eng hours. You don’t want to have somebody trying to decipher what every line is or like, “What is this all about?” It’s more a matter of, long-term, you’re creating a ton of company value by everybody contributing and saying, “I’m going to take the extra time to make sure this is documented in a diligent way,” because it makes the whole company better.

Maxine Whitely (07:17):

Ian, we were talking about this, this morning, that a lot of joining a new company or, Ben, in your example, acquiring a company, is understanding the narrative arc of where a project or company was, where it is now, where it’s going, and engineering documentation builds this log of the narrative arc. So, you see a feature in its first state and then the next engineer updates it, and they update the docs with it. So, you get to see how a piece of functionality or a piece of code changes throughout its use cases, and throughout its life cycle.

Ben Grynol (07:52):

One of the things you’ve been doing, Steph, if you want to jump in with it, is everything around, Loom, right? So, that’s not super common. Maybe it’s becoming more common, but it’s not super common in documentation in general, and it just makes so much sense from an eng perspective because you can walk somebody through things so much faster.

Steph Coates (08:10):

Yeah. I could sing praises to, Loom, all day long. I’m in love with the tool. I guess, continuing on the conversation that we were just having, the way that I view documentation is that it benefits three groups. It benefits the individual that’s writing the code and putting up the PR, and it benefits the immediate group of other engineers that are working with that on the team. Then, like you had said, Ben, it also benefits the organization as a whole, in terms of building trust and continuing this narrative arc, like you had said, Maxine, around just being able to follow this storyline rather than inheriting or joining a company where you’ve just got this big mess of spaghetti and it’s very hard to understand it.

Steph Coates (08:49):

So, in terms of, Loom, I have found that joining a remote company, and actually I have to give a lot of props to Justin, because he had modeled this to me. I remember, when joining the company, it felt so weird to record myself talking at the computer screen, and my head’s in the corner, and it felt very unnatural. Now, in terms of the three groups of people that it benefits, in terms of that, being able to write code and put up a PR, and then feel empowered to take the time to document what I just did, in terms of recording a, Loom, writing documentation…

Steph Coates (09:29):

I guess this is a little bit of a tangent, but something that I really appreciate about, LEVELS, is, because it’s an engineering-led culture. I do feel, I don’t know if, “Empowered,” is the right word, but I do feel like I’m given adequate time to do both, to both write the feature and to document it. I felt, at other companies, where there’s such these strict timelines, by people that may not understand all the things that need to go into fully shipping a feature, that they say, “Oh, well, this should only take two days, or three days.” So, you’ve got to ship it and then documentation becomes afterthought, and we don’t have the time to do so. So, with, LEVELS, being given the trust to say, “Okay, I’m going to write this, but I need enough time to also document it, to record the, Loom, to write the docs,” that feels really great.

Steph Coates (10:11):

So anyway, back to the original point, I think being able to summarize what I just did, of writing a feature and then talk through it, to benefit other engineers, it’s that mentality of, you understand something so much more after you teach it to others. So, being able to write a feature and then verbally talk through it, I understand what I did so much more. So, that’s such a hugely beneficial part, is this closeout review to shipping the feature, and before I even put up the PR, I might notice, just through talking or the code and recording myself doing it, I might notice little bugs already, or things that I want to fine-tune. So it benefits me, in that way, of doing this full circle, closed loop of building the feature.

Steph Coates (10:51):

Then, Looms are so helpful for just quickly getting context around. I used to hate reviewing PRs at other companies, because they would be massive and thousands of lines of code change, and it would take you 30 minutes to an hour plot to review, to get the full context, to get up to speed, to feel confident in approving that PR. Now, getting that immediate context through a recorded video of someone walking through a demo of the actual app, and then also walking through the code, and giving the context and the explanations for why they did what they did, is this expedited process to allow me to have the confidence to approve that PR.

Steph Coates (11:28):

So yeah, I think that, Loom, has been, especially in an asynchronous culture, where that was definitely a fear of mine, is, “How is it going to go, when I can’t just turn to the person next to me and ask them a quick question about why they did what they did in this PR, or even just have them walk me through it in face to face?” So, Loom, feels like this beautiful bridge to still get all the benefits of remote culture, and if anything, maybe more, because we’re forced to document more, when you can’t just tap someone on the shoulder and ask them what they meant with something and answer a quick question. So yeah, I guess that was a very long, roundabout way to say that, Looms, and recording videos, and having this both verbal and nonverbal, because we’re recording our faces, and screen recordings, attached context to just the PR code changes.

Ian Schumann (12:14):

I think, on that first point, the bit about, on the engineering team, we’re not just given the room to write documentation, but it really is considered part of the job, right? You haven’t shipped a thing. You haven’t made your PR ready for review, unless you’ve adequately documented it, or recorded the Loom. To me, that fits in with the larger picture, at, LEVELS, of, comms is a crucial part of the job. It doesn’t just fall into the cracks, right? Everybody, on the engineering team and beyond, across the whole company, communication and presenting an audit trail of what you’re doing, and sharing, communicating your thoughts and explaining your reasoning, this is part of everybody’s job. Time gets allocated to it on purpose, right? So the way that takes its shape on the engineering team, in part, is like you said. Unlike at many other companies, where you’re concerned with shipping the feature, shipping the code, here, we are also concerned with shipping the ideas to our teammates, to make sure that it makes sense to them.

Steph Coates (13:06):

Yeah, absolutely. I think the reason it’s been so successful with that is not because we have this line in some memo that says, “Oh, engineers document things.” But for me, it’s been successful because I’ve seen it modeled by other engineers at the company, of, “I joined, and I saw Justin recording Looms, and I saw [Ginlu 00:13:23] writing up a notion doc about how she re-architected the user feed,” and being able to see it done by other people automatically instills that in you, of, “I want to behave the same way.” So yes, seeing it modeled by the rest of the engineering team, I think, is just an easy way to adjust into that same culture, rather than it just being this bullet point on some notion doc or memo, where we may be saying it, but we’re not living it. But in reality, at, LEVELS, we really are living it, and it’s so easy to assimilate into that culture when it already exists.

Ian Schumann (13:53):

Yeah. The other thing I really connected with, to what you said about, when you’re at the end of, maybe you think you’ve written all the code that you need to ship with your PR, with your feature that you’ve just written, and you get ready to record your Loom, or even you start doing it, or you start writing your summary and you discover that, “This one thing that I wrote is difficult to explain, and it’s difficult to explain because it doesn’t make sense,” right? I think that mirrors my understanding of what it means to write. Just, the general world of writing blogs, writing books, writing novels, whatever.

Ian Schumann (14:20):

I think Josh shared something on threads about this a few weeks ago, from a blog author. The author was dispelling this idea that, “I know what I intend to write when I sit down to write a post,” right? No, no, no. That’s not how it works, right. You sit down to write, and your ideas get clarified as you go through the labor of clarifying what you’re trying to communicate. The same thing can happen with PRs, with code that you’re shipping, right? You might discover that you’ve gotten the thing working, but once you decide to document it, or communicate it to somebody else, it actually doesn’t make any sense, until you’ve actually spent the time drilling down into it with your head down, in this little cave of inventing this functionality, right.

Ben Grynol (14:56):

For Max, how have things changed as far as, you saw process and documentation at a very established company, and how have things changed as far as the way we’re doing things at a startup? Are there things that were going great at Apple, that you’re like, “Wow, that was really rigorous and good documentation,” or maybe it was it too much, or are there differences that you’ve seen that are more or less effective at either company?

Maxine Whitely (15:25):

Yeah, that’s a great question. I actually think even unwinding a little bit farther is maybe helpful, because when I was at Apple, it was also during the pandemic. So, it was remote, and there were a lot of communication norms that got built in during the pandemic that I think weren’t the norm beforehand. So, from my understanding, there was a lot of back and forth in person with PR reviews, when you could be in the office, and then when you could no longer be in the office, folks on my team got a lot better about writing more in-depth descriptions of their poll requests, all that kind of stuff.

Maxine Whitely (15:56):

But, at a company I was at before Apple, it was a really small team that was moving really quickly, and I was in the working in news. So, things were happening very quickly and there was almost no documentation. So things would get approved and merged so quickly, no docs on any of the code that we added to the code base. So, it was really challenging for me, when I was starting on that team, to try and get my bearings about, “Okay, I’m going to build upon this feature, and I have no idea how it came to be, if it’s still important, if it’s even being used in the way that it seems to be used.” Whereas, when I joined, LEVELS, I haven’t been here for that long, but I’ve been able to sense-make around the code base so quickly, either because of documentations about the intentions of the projects, or of the outcome of the project.

Maxine Whitely (16:45):

The one other thing I’ll add is, I think the quantity of Looms has seemed to really go up since I’ve joined the company. A lot of different engineers are adding it to their poll request, as a result of Ian adding a poll request template that asks for a Loom. So, before you even submit your code to be reviewed by other engineers, you have to record a Loom, in most cases, unless it’s a small or urgent fix. That’s actually allowed me to get into the reviewing cycle more quickly, as well, because as a new engineer, it can be hard to feel like you have enough context to give valuable input to your teammates. But, when you have that context given to you, someone else’s mental model is pre-created for you to step into, find the holes in, then it’s much easier to give feedback than I have found it at other companies, or on PRs without Looms.

Ian Schumann (17:36):

Yeah, well said. “Step into the mental model.” I like that.

Ben Grynol (17:41):

It’s interesting because there’s, without a doubt, this dichotomy between moving fast and being scrappy, like, “Startup mode,” air quotes, “Startup mode,” and being rigorous and with documentation, and you can be too far on either side. Sure, everybody wants some symbiotic homeostasis of this perfect world of being scrappy and documenting, and you’re still moving fast and not getting bottleneck. That’s, without a doubt, something that people aim for. But, here’s where it gets interesting is, you move too quickly, you don’t document things, you have an outage. What do you do? I’ve seen this happen time and time again, and outages that are highly sensitive as far as time KPIs, right?

Ben Grynol (18:27):

So, in the world of on-demand food delivery, there is a lot at stake as far as when people have certain KPIs for getting their food. You’re talking about minutes making a difference. People become irate if things are a minute late. When you’re talking about a marketplace where there’s a lot of economic transactions happening all at once, outages cost you a ridiculous amount of trust, a ridiculous amount of money, a ridiculous amount of effort, all of these things. So, there’s an outage and a bunch of engineers break open their laptops and trying to figure things out, when there isn’t documentation. They’re like, “Hey, where is this?” “Well, go talk to that person,” who they can’t get ahold of, and all of a sudden it becomes this huge headache, and you’re just like, “Well, if we would’ve just documented this…” Maybe if we slowed down, you could argue that we wouldn’t have shipped fast enough, and all these things.

Ben Grynol (19:19):

But the other side is, maybe we would’ve been able to mitigate this outage from being, instead of out for three hours, you’re out for four minutes. Maybe that’s a little extreme, but you can minimize that window so much, where it’s like, “Oh, the outage was 12 minutes.” That’s actually reasonable, where it’s like, “Oh, somebody fixed it. They figured it out. They knew, and it was somebody who didn’t even write the original code, they were just familiar enough, or they were able to figure it out because there was deep enough documentation. So it’s a balance between both, but you need speed, but there is, without a doubt, a time and a place for rigorous documentation.

Maxine Whitely (19:59):

Ben, to your point, it almost sounds like, when you think about things like technical debt, which folks talk about a lot when you’re trying to build quickly, so you build something maybe in the not most optimal way as a way to ship it, a good way to mitigate technical debt is to avoid documentation debt. So, acknowledging inline, in the code, “This was done weirdly. I know that, here’s why, and here’s how to make it work.” Then, sure, it’s technical debt, but the piece is in place, and the next person who needs to debug it or improve it already has the context to then make that happen so much more quickly.

Steph Coates (20:33):

To your point, Ben, Maxine and I, I think we were actually to talking about this in Denver when we were walking around, but in my mind you have to pay a price for something, either now or later, and in the sense of documentation and tech debt, velocity, and speed, and scrappiness is the short-term gratification, I guess, to be like, “Oh, we’re going to release this really quickly,” but you may end up paying for it in the long-term if you don’t take those little steps to document those things, and make sure that the foundation is built well. So, I guess the way that I think about it, and something that seems to have worked really well at, LEVELS, so far is, I don’t know who said mental models, but the idea of building in just these little habits and these inconsequential things to…

Steph Coates (21:20):

I guess, the way that I think about it is a lot of companies let documentation fall by the wayside, and then it becomes this giant, Hulk task of, “Oh my gosh, we’ve got to document the whole code base,” or, “Oh, we have to write all the test suites at once, and this is going to take months and we can’t ship any new features, so let’s just keep avoiding it.” But in reality, I think because, LEVELS, has said, “Oh, all we want you to do is record a 10-minute Loom, and then we’re going to,” and thank you to both of you, Maxine, and Ian, I think pushing for, “Let’s attach the Looms in the commit messages, and let’s make this really easy to trace and circle back to,” these things don’t take that much time.

Steph Coates (21:56):

It’s not a week, or a month-long effort to undergo, to fix a lot of this tech debt, it’s just these little habits built into the day to day engineering work, that allow us to still move with speed, and velocity, and scrappiness, but, and don’t take too much time away from shipping and learning fast, but don’t leave us with this, months down the road, we think, “Oh crap, we avoided doing any technical documentation, and now we need to,” whether it’s because of an outage or just because of with scaling, we found that it wasn’t sustainable to onboard new engineers because they’re lost in the code base. We avoid that because we were taking the little steps from the get-go, to make sure that we were building a strong foundation.

Ian Schumann (22:32):

Yes. The incremental effort, rather than a Herculean, one-time effort, right? In the world of self improvement, habit formation, there’s the idea that small efforts, applied consistently over time, will produce bigger results than monumental, Herculean efforts that are applied inconsistently over time.

Steph Coates (22:51):

Yeah. I love that. It’s like me thinking, “Oh my God, I need to do a 10-day fast to overhaul my health,” versus just doing small intermittent fasts, or just, like you said, the small steps are way more effective in the long run than some big Herculean effort.

Ian Schumann (23:05):

Well, I got to connect the dots from something you said earlier, Max. I think you said something about the comments that are left in the code, the time the thing is written for the first time, that say, “This ought to be fixed later,” right? “Here’s a little bit of tech that someone should fix this later,” right? I think that goes back to the narrative arc idea. A code base is something that evolves over time, and the team working on it has different ideas about what the code needs at different times, just like teams need different things at different times, different stages of a company’s life cycle, or a team’s life cycle.

Ian Schumann (23:38):

So, one of the other, I don’t know, repeat parables, or things that I always go back to and talk about a lot with engineers, especially new ones coming on to a team and getting their bearings, is, it’s very easy to make the mistake of looking at anything that has been written before you, that seems to be working, and assume, therefore, that it was written correctly. That the author thought it was perfectly well-designed, and everyone is happy with how it’s working today, right? That is nothing but a confusion, a status quo bias. The reality is, if you go back and look at anything that has been longstanding in a code base, or even anything that was written recently, there were compromises that were made at the time that it was shipped, and the author or the authors know that.

Ian Schumann (24:19):

So, when you drop little hints, either into the code base directly or into documentation that’s outside the code base, you give the next person a sense of what is safe to tamper with, and what still is a work in progress. It may be working today, but it really still needs some TLC, if it’s going to go the long haul. Informing the future generations of devs about that is crucial, and that, to me, I think that’s another win from documentation.

Steph Coates (24:44):

Yeah. Even just to touch back on the, Loom, idea of, I found, Looms, to be so helpful for that, because not only are you just looking at the code, but you’re getting to enter the brain of whoever wrote it. I remember this one time that I was going to fix some bugs, and I went into the code base and looking at the, Looms, that How and Andrew had recorded, giving the high level of, “Here’s how this whole thing works,” like you had said, Ian, of, “Where did we have to compromise? Where are things really sturdy?” It gave me so much more confidence to go in, without needing to spend days or weeks inspecting every little element to understand it myself. I got to get up to speed so much more quickly just by being this fly on the wall to when it was being built, even though I wasn’t even at the company at that point. So yeah, being able to get the full context through documentation, I think, is so, so useful.

Maxine Whitely (25:32):

I’m sure Andrew and How were really happy, too. They didn’t have to re, it’s like you’re automating your job of explaining.

Steph Coates (25:37):

Totally.

Maxine Whitely (25:38):

Would you rather explain once, or every time a new engineer joins? Because, it’s fine when there’re seven engineers, but then there’s 30, and you don’t want to explain the feature you wrote 30 times [crosstalk 00:25:47]-

Steph Coates (25:47):

So, that becomes their full-time job, is just hopping on Zoom with us to explain things. Yeah.

Maxine Whitely (25:52):

Not fun.

Ian Schumann (25:54):

That’s what happens at a normal company, to what Ben said, when you have an outage, everyone panics and they go, “Well, where is so and so? They’re the only ones that understand this?” “Well, it turns out they got so burn out that they had to take a vacation, right, so you can’t reach them right now because they’re too busy answering everybody’s questions, they had to get out the office.”

Steph Coates (26:09):

Yeah. Can I tell a quick story? So, something that I will never forget is, the first company that I worked at was a large corporate finance company, and very much an in-person culture, very much a, you join and your onboarding is literally just flailing around for the first six months until you’re immersed enough to fully understand what’s going on. I know a lot of big companies function like that, because there isn’t a big emphasis put on documentation and it’s this mentality of, “Oh, I can just tap this person on the shoulder and get an answer.” But, like you had said, Maxine, that’s not scalable. That’s not automating it. That person has to context-switch every time that you do ask them a question, and something that’s burned into my memory, and I think why I feel really passionate about remote work in documentation now is, I worked in the office and I was really gung-ho about remote work. I wanted to travel, I wanted to live elsewhere.

Steph Coates (27:00):

I asked my boss, I said, “Is there any feasibility,” this is way before COVID, “That we would eventually have some sort of hybrid model, or I could be remote on this team?” He said, “Absolutely not.” I asked him why, and he gave an example of, the one infrastructure engineer on our team was so crucial in terms of outages and bugs, and it was the worst case scenario, bus situation, where if he got hit by a bus, the company would fall apart, because he was that integral to making sure things worked day to day. My boss said, “Well, if everyone goes remote, I can’t tap so and so on the shoulder to ask him when there’s an urgent problem.” That just speaks to this problematic culture around needing people in person, and needing this immediate answer to distract someone from being able to do deep work, because we don’t have our stuff together in terms of things being well-documented, so you have to rely on this one person to be the bottleneck whenever stuff hits the fan.

Ian Schumann (27:52):

It’s so funny he was talking about that as a feature, because it’s a horrible bug.

Steph Coates (27:55):

Exactly.

Ian Schumann (27:55):

Right?

Steph Coates (27:55):

Yeah.

Ben Grynol (27:55):

A horrible bug. There’s this idea of cohesion that we should jump into, that we can have this perfect world where everybody’s aligned, it’s like, “Yes, let’s document everything.” That sounds like a good state, but one of the failure modes of that is a lack of cohesion. Not in process, not in people agreeing, “Yes, let’s document,” it is how a team goes about documentation. So, failure mode is like, hypothetically, let’s just make up the scenario. Ian, I will never be doing PR, so it’s kind of fun. Ian puts something out. He is like, “Hey, can you do a review on this?” and I start to give some feedback, but it’s in the Loom, right? It’s comments within a Loom. So, the next person who’s going to like discover what actually was the feedback or what was changed, it becomes hidden documentation.

Ben Grynol (28:50):

You can extrapolate this across documentation as a principle, in a company, but if there is a lack of cohesion, where there’s some feedback given in, doesn’t matter which platform, Slack, Threads, email, however people go about their communication. If there’s a lack of cohesion, where it’s happening everywhere, that’s actually a failure mode where, it’s still better that you’re documenting things, but it’s not great that things are happening in so many places.

Ben Grynol (29:19):

So, how do you go about this idea of cohesion? A, where do you do it? From a, LEVELS, perspective, maybe highlight how are we going about documentation? What platforms is it being done on? Where is it getting placed? Then, how do you go about this idea of keeping a cohesive documentation process?

Maxine Whitely (29:39):

Ian, I wonder if you want to talk about this, with the issue you were working on last week? The, Threads, to the, Notion, to the PR, and that process.

Ian Schumann (29:49):

So, let’s take the easy question first. Where do we do this now? What are the different places? So, like most of the rest of, LEVELS, the primary, the brain, the information storage, is, Notion. We have a growing knowledge base under the engineering heading in, Notion, and inside that are how-tos, and explanations of things that engineers on this team will need to know day to day. There are norms and culture documents. There’s a new memo out about our aspirational documentation standards in software development. There are also design docs. There’s a special little subsection of the engineering Wiki in, Notion, that is collaborative documents that are created, that are spun up just for the purpose of making an important design or architectural decision when a new feature, or a new system, is being built. So, there’s a lot going on in, Notion. There’s a lot of long-term information that goes into, Notion.

Ian Schumann (30:50):

On the other end of the spectrum, the more ephemeral stuff is in the code base, or it’s in PR comments. So, code base is always changing, it’s a living, breathing entity, and it’s evolving and growing through time, just like this team. So, code will appear there and it will be commented or to some degree or other, and then those comments and that code might change later, and evolve or disappear later. Poll requests are temporary spaces in GitHub. That’s where code review happens, for the most part. That’s where code gets finalized before it is shipped. To me, it seems most of the direct debate, and revisions, and discussions about how code should be written, most of that happens in PRs.

Ian Schumann (31:32):

Then, in between all that is, Threads, our replacement for Slack, right, that we use LEVELS-wide, and the engineering section of, Threads, is pretty lively. People do sometimes escalate questions from a PR into a Thread, to get more exposure, to get more interaction than you might get on a PR. If it turns into a big discussion, then that might get escalated to something that lives at, Notion, or a design document. So, that’s the hierarchy, that’s the ladder as I see it. I don’t know, what do you guys think? Did I miss anything?

Maxine Whitely (32:02):

There’s one more that I think is important to shout out, which is, Linear, which is what we use for our task tracking. So, week to week, we create our sprints in Linear, and that really is just for allocating time, but we might put a collection of resources for a certain issue we’re going to be working on into a, Linear, ticket. So, for example, if I’m working on feature X, and Ian and staff have also both worked on a previous version of feature X, we might all dump a bunch of links or comments in there. Then, when I start that task, then I have that context to start writing code with.

Ian Schumann (32:37):

We also have product-related discussions in there, right. Oftentimes, the person writing the ticket in, Linear, might be someone from the product team, and so we’ll ask questions about that there, too.

Steph Coates (32:45):

Yeah. The way that I view it is, in terms of, from most permanent to most ephemeral, is, Notion, is the database, and that’s where you can find consistent, reliable information, and then, Threads, I think, and then, Linear, and Figma, and then GitHub. Those are on the more transient, less permanent side. But I think that there was a point of friction a couple months ago, where we were adding all these new tools, we had just added, Linear. Especially with, I’m not sure which project I was working on, I think it was the guided day review stuff, and there were so many duplicative conversations happening between, Figma, and, Linear, and, Notion, and, Threads, so a couple of us got together to say, “How can we consolidate this?” and set different intentions for different platforms.

Steph Coates (33:37):

Actually, even though we’re using a multitude of tools, I’ve found it pretty seamless now, where I do know that if I’m going to have a technical discussion about the way that the code is written, that’s most likely going to happen in GitHub. If I need to talk about product or design decisions, that’s going to happen in, Linear. If I request for comment on some big architectural decision, that’s probably going to happen in, Notion. So I think that we’ve actually made a lot of strides, in the sense of, we do use lot of tools, but they also serve a very specific purpose.

Steph Coates (34:04):

I think I have my own process now, for… I’ll give an example of, if I need to figure something out, find information about something, first, I’ll go to, Notion, and I’ll search it on, Notion, and I’ll get the high level context. If I can’t find anything on, Notion, then I will go to, Threads, and I’ll search in, Threads, or I’ll look through the forums that it might be posted in. Then, if neither of those things pan out, then I will either create a new Thread, or create a new source of information, or to find the answer, and then take action from there of, “Should this be posted in, Notion, should this be marked as a decision in, Thread, so other people can then quickly get to the decision that I just took a little bit more time to get to?”

Steph Coates (34:43):

But yeah, I guess that’s, long story short, just getting the processes in place where you know what each tool is used for, and then making sure that you fully circle back after. If there is something missing, making sure that you do fix the problem, so then other people that fall into that same thing, down the line, don’t have to go through that same exact process.

Ben Grynol (35:00):

Yeah. That’s the cohesion, right? That’s the idea of establishing an agreed-upon way of working and cohesion within a team to say… And correcting it, right? When things start happening, if occasionally, again, let’s just make up situations. Occasionally, a conversation starts happening in, Loom, comments, and two people can go, “Let’s pull this into platform XYZ,” it doesn’t matter which platform it is, “As it relates to whatever’s being discussed.” Because, the next person, to what Ian was saying at the very beginning, is setting up whatever you’re doing for the next person, so that there’s the parable of, “Oh, that was me,” so that you remember what was done.

Ben Grynol (35:42):

You can extrapolate these examples with naming taxonomy, for naming layers, creating really well-thought-out design files, right? The next designer to come into some creative cloud file, like you’ve got something in, Illustrator, and the layers aren’t named properly, and somebody’s going, “Layer 43. What?” and you’re trying to decipher. It causes a lot of confusion, and to this point of using, Notion, as this database, if you want to call it that, if you don’t have good naming taxonomy and naming hygiene, then that becomes a challenge, too. Because, a document called, “Day score update,” is just a terrible thing, because there could be a hundred day score documents. So you have to start to get, you’ve got the taxonomy of, and I haven’t looked at it, but maybe there’s a page called, “Day score,” and then within, “Day score,” there are all these sub-pages of the update, the date, the timing, and you go through, and being able to be a forensic investigator when it comes to trying to break down what exactly happened in the past is integral.

Ben Grynol (36:51):

It’s maybe not all for naught, but it’s pretty close, if it’s just, you named documents, “Doc A,” “Doc seven,” those aren’t going to help anybody find anything. So, if you do document, but you don’t take the next step of being rigorous and saying, “This was done on this date, by Ian, by Steph, by Maxine,” it doesn’t matter. If you don’t have just enough detail associated with it for the next person to say, “Oh, I understand when this happened, why it happened, and I’m not trying to decipher like what it is that happened.” There’s just enough information for me to go, “I get how they got to this decision.” Back to what Ian was saying before, too, and assume Ian wrote whatever it was, and Ian has a line at the bottom that says, “And I think this is janky.” I know I’m not going to offend Ian if I’m like, “Hey man, I’m going to rewrite this thing.”

Ian Schumann (37:45):

Right. Right.

Maxine Whitely (37:46):

Well, Ben, to your point, it sounds a lot of what we’ve been talking about, it seems like curating the experience of other people experiencing your work. How can you make it as easy as possible and create this guided journey through your own work? For yourself, for other people. I think that’s a lot of what the best teammates I’ve had do, where they have this amazing way of externalizing their thoughts, and their work, and their progress, so you’re always in lockstep with them. The cohesion is built into the way that they structure working on the problem, and it seems like good documentation is such a key component of that. It’s like the thing that keeps the good process on its rails, or keeps the curation moving forward, if that makes sense.

Ben Grynol (38:33):

Mm-hmm (affirmative).

Ian Schumann (38:34):

Yeah. Well said.

Steph Coates (38:35):

I think that the idea of, not only taking the time to create documentation, but maintaining organizational hygiene, and I think, Notion, does this pretty well, of not only do we have… Imagine if everything in, Threads, and everything in, Notion, was just a flat hierarchy, and you just had to use the search box to find something, and like you had said, Ben, naming taxonomy might not be perfect, and you might not even know what term you’re looking for, to find a certain document. So, it would be a nightmare to have to tread through hundreds and hundreds of docs to find what you were looking for. But, the way that, Notion, is structured right now is, say, I’m looking for something related to engineering, and I’m looking for a specific architectural design doc, so I would know to go into engineering, and then into design docs, and then scan through them and say, “Oh, this is the one that I’m looking for.”

Steph Coates (39:20):

So, I do find that having a structured hierarchy, even if you don’t know exactly where you need to end up, knowing the path to start to go down to, is really, really useful. Same with, Threads, if we had one channel where every single thing was posted, it would just be information overload. So, being able to say, “I’m only going to focus on eng channels and my specific project folder, and everything else I can keep up to date with when I have the time to,” but otherwise, you’re context-switching so many times throughout the day, trying to process all this information, that may not be relevent to me in the moment. So, having these intentional silos of information, I think, can be really useful, just to get to process the information that you need to at the moment.

Ben Grynol (40:01):

Making it intuitive is what allows teams to be asynchronous, right. Where it’s like, once you have enough of a foundation to say, “I think I understand where to find things,” you can usually find them. You usually have some mental model as far as the path, where it’s like, “Before I go and someone, I’m going to take one extra second just to take this path, this path, or this path,” in whatever platform it is, let’s assume, Notion, for argument’s sake, but, “I’m going to take this path. I’m going to try these things. Oh, there it is. I found it.” I couldn’t find it through search, right, Notion search can be great in some instances, and can be challenging, just given fuzzy strings, but that’s neither here nor there. You want to make sure that whatever you’re doing is intuitive.

Ben Grynol (40:45):

The question being, so we’ve talked about all these things. What can companies, what can teams do, that might not be as far down the path of documentation? They realize it’s important, they know that it’s important, but they set the calendar reminder where it’s like, “I’m going to start next Monday,” and the same way people do with fitness goals, with whatever it is, “I’m going to start doing something in the future,” because it just seems so overwhelming to all of a sudden jump in and be like, “Let’s start documenting.” So, you never end up doing it, because it’s really easy to punt. So, given each of your experience, maybe we’ll start with Steph, go, Steph, Ian, Max, what are some things that teams can do to start documenting, so that it doesn’t feel so overwhelming?

Steph Coates (41:31):

Yeah. I think we touched on this a little bit earlier, but just the idea of, it becomes easy to avoid when it is this gargantuan task, and rather than thinking, “We need to fix this all at once,” just building in those tiny, small habits daily, consistently, to alter the path going forward from here. So, even something as small, “Oh, every PR from here on out, we’re going to record a Loom, or, “We are going to,” I think that’s the best example for something quick is, if we want to start to document better, similar to what we’ve done at, LEVELS, that has that ramped up in the past few months has just been, “We’re not going to go back and,” for a company, let’s say, that doesn’t have good documentation, you don’t have to go back and overhaul the entire code base at this moment, but, “From here on out, when you write code, put in little comments that are helpful to get someone else up to speed, and then record a, Loom, every time you put a PR up.”

Steph Coates (42:23):

So, that only takes an extra 20 minutes of your day, and I think that just correcting the path going forward will allow you to start to make progress so much faster, rather than thinking that it needs to be this, like you said, giant overhaul. It’s fascinating, how applicable this is to both engineering and documentation, but also the mission of changing health behavior, as well, of people will say, “Oh, I need to drastically change my diet,” or, “Totally change my lifestyle, in order to abide by who I want to be in the future.” That rarely works, because there’s too many changing factors at once, and it becomes overwhelming, and we give up. So, just changing one little small habit per day, whether it’s, “I’m going to have protein before I have my bowl of fruit,” or something like that, can make way more measurable impact than a giant overhaul at once.

Ben Grynol (43:15):

Totally. It’s all about, just stop eating Starburst. That’s the first step.

Maxine Whitely (43:20):

One small thing.

Ben Grynol (43:21):

Stop that. I love it, though. Yeah, recording, Looms, it’s such a simple bolt-on, as opposed to an entire process undertaking of, “Great. Now we have to sign up for the…” Assumes teams aren’t on any platforms, if they use any, it might be something drive-related like, well, occasionally we will have a Google doc that floats around with some comments. It feels a lot heavier to undertake this idea of, “Okay, we have to get all these platforms and let’s try this, Threads, thing, and not Slack.” That’s not what we’re trying to be prescriptive with. It’s more a matter of, what are these little hacks that you can do that have changed the way you go about work? What are you thinking, Ian, as far as some of things that teams can do to get deeper?

Ian Schumann (44:04):

I totally agree with the, “Adopt a small effort that you will apply incrementally.” I think that’s by far the easiest thing for a team to try to start doing, a team that is already busy and feels overloaded. Just adopt something that will add five minutes a day, and start with that.

Ian Schumann (44:22):

As I’ve thought about PRs in particular, and communicating about them, as I’ve grown as an engineer, I’ve had to get honest with myself about, “What are the headwinds and tailwinds that are in play here?” So for me, actually, you happen to have rolled the dice and ended up with three engineers here on this podcast that are all communication-oriented, somewhat extroverted, and sociable. This is not a representative sample of the engineering world, right? Not that these are, we’re probably all above media in these dimensions. To make matters worse for me, I have a liberal arts background, so I’m hyper verbal. I love writing, and so an articulate PR description, that’s probably longer than anybody wants to read, will just come out of me by accident. That’s not to toot my horn, that’s to emphasize how what feels normal to me is abnormal to a lot of people, and there are a lot of absolutely brilliant engineers, who can run circles around me technically, who do not enjoy writing in plain English prose about what they’ve shipped. Right?

Ian Schumann (45:24):

So, one lesson, one takeaway for me here, one learning, has been, Looms are a little easier, I think, for most people to produce than multiple paragraphs of description for a PR. Looms do, admittedly, feel a little awkward to record, but I think the guidance for recording a PR on a, Loom, is to imagine that you’re just sitting down with one of your colleagues, and you’re going to walk them through what you’ve just written and give them a quick orientation. It’s going to be maybe three to five minutes. If it’s a big PR, maybe a few more minutes than that, and that’s it. It doesn’t have to be super well-produced, it doesn’t have to win an Oscar. It’s just a short, conversational little walkthrough video, and all of this guidance is in the hope of making it easier to do on a regular basis. So, I’m with Steph, I think, Looms, are a big step forward. I think they manage to hit a sweet spot, hopefully, for most people, in terms of sustainability, feasibility to adopt quickly, and start doing,

Ben Grynol (46:24):

It’s so funny about the Looms. The idea that, when recording them, you often hear, “Oh, it just feels so awkward. I’m sitting there, I’m recording, I’m doing it.” But as a viewer, it’s not like, “Man, that’s so weird. Look at Ian in the corner, talking.” The viewer views it as this immensely helpful thing. They’re like, “I appreciate that ian took the time, and I can pause it, I can think about his thought.” There’s so much benefit to having it, but the person recording, it’s always like, “Whoever’s receiving is going to think this is so weird.” It’s the complete opposite. So it’s funny the way the human brain tricks us into all of these irrationalities that we have. But, what are you thinking, Max? What are some of the takeaways that teams can do?

Maxine Whitely (47:13):

Yeah. Great points, both Steph and Ian. I think my recommendation is maybe a little bit different, and it’s thinking about, even before you get to the poll request step, how can you build documentation into your process, so it’s not so overwhelming at the end? To Ian’s point, if you don’t like writing, or you’re not super excited about verbalizing your thoughts in whatever medium works for you, do it in the way that feels most comfortable to you, and that will help your coworkers the most, if you’re an engineer.

Maxine Whitely (47:43):

So, if you’re a single engineer listening to this and you are trying to influence your team to be better documentors, maybe you just start by inline commenting everything that’s semi-unclear, and when you’re leaving PR reviews on another teammate’s PR, you say, “Hey, can you set a doc here?” Which Ian said for me a bunch of times, and it’s been really a helpful reinforcing technique to remind me, as I’m thinking through it, in the process, just add the doc that captures my current state in the process. So, I think this is really helpful for individual practice, and then it’s also really helpful for making it seem exciting to your teammates around you, because they’ll reap the benefits of your built-in process documentation.

Ben Grynol (48:29):

When everyone’s doing it, everyone follows suit. If there’s a team of, let’s just say it’s 10 people, nine are documenting rigorously, no-one wants to be the one person that’s like, “Well, I’m just not going to do it.”

Maxine Whitely (48:40):

Totally.

Ben Grynol (48:41):

There’s the point of critical mass, where no-one wants to be the outsider when the social norm is, “We all do this thing.”

Maxine Whitely (48:49):

When the experience is so much better as a result of doing the thing, it’s like, “Oh, are you going to make your teammates’ experiences worse by not doing this? That’s kind of crappy. Don’t do that. Just write the doc.”

Steph Coates (49:04):

One point I want to touch on with what you had said, Ben, with, Looms, feeling awkward at the beginning. I guess the way that I frame it now is, any new tool, or any new habit or behavior, when it’s so unfamiliar, it does feel uncomfortable, and we want to shy away from it, and especially being thrust into this, now, very much more remote-friendly world now, as humans, we’re not used to recording ourselves on a screen and talking to a computer. So, it does feel a lot less intuitive than just chatting with someone face to face. But, I have found that just through and, Loom, has done a fantastic job with this as a product, it is very seamless, and it is very easy, of just using the Chrome extension, or using the browser or the desktop extension to easily record something, and then it uploads to the cloud.

Steph Coates (49:47):

Through just seamlessly, slowly onboarding onto this tool, I said this earlier, but I love the tool, and not only do I use it for PR reviews, but now I use it for just casual communication as well, of, if I need to chat with someone. Ben, this happened between us a few weeks ago of, just catching up with a coworker, or knowledge transferring of just using it, and becoming so comfortable with it. I guess you have to go through that transition period of being, “Yeah, this is a little weird and unfamiliar,” but eventually it’ll become natural. So, I would encourage anyone that maybe doesn’t feel super in tune or comfortable with these tools yet, try them for a little bit and see where you end up a week or a month from now, because I’m shocked at how I’ve been able to ingest these tools, and now they’ve become such a big part of my work life.

Ian Schumann (50:32):

Actually, back on the cohesion topic I wanted to shout out. So when it comes to, Looms, and commit history, I think Max had an awesome suggestion a few weeks ago, when we were codifying some of these norms. The way you raised the cohesion concern was, if information gets buried in too many different places or it’s not adequately searchable, right? Then, you also used this term, “Forensic,” like there’s a forensic investigation in some cases. I think that’s a great term to describe the search pattern, the access pattern, the way that we look for information as developers, when we are going for through the parable situation of, “Who’s the idiot that wrote this?”

Ian Schumann (51:12):

When you’re in that situation, you’re in a specific part of the code base, you’re in one or two files, or something. You’re probably not going to go back to some global search engine, like, Notion, or, Threads, and just search for anything that has to do with that part of the code base. Instead, and GitHub, they already have a concept of contribution history, right? So, Max was suggesting a few weeks ago, when we were getting more formal about the, Looms, let’s embed the Loom summary video into the merge commit when a PR gets shipped into the main branch, the trunk branch of the code base.

Ian Schumann (51:46):

That’s a bunch of engineering gibberish, but what it means is, when you’re in that parable situation, and you have your editor set up in a certain way, you can basically just hover your mouse over a specific line of code, and what will pop up is the last PR, the last contribution, that hit that line of code. If people are following the suggestion that Max put out, they will immediately see a link to the, Loom, that it documents that contribution. So you can go from some inscrutable line of code that is frustrating you, to step into that person’s mental models at the time they wrote it, with so little resistance. Even though those, Looms, are not searchable, they’re easily accessed in exactly the way that you want them to be in that moment.

Ben Grynol (52:29):

All about removing in the friction.

Maxine Whitely (52:32):

I love it.

Steph Coates (52:36):

I always wonder what the closing… In all the podcasts how there’s the off the-

Ben Grynol (52:44):

Close tags?

Steph Coates (52:44):

Yeah. The closer. I’m always wondering, what’s the closer going to be?

Ben Grynol (52:49):

What do you want it to be?

Maxine Whitely (52:51):

Your code’s not done until you document it. Just kidding.

Steph Coates (52:55):

Can we put that video in, of Maxine throwing her arm up in the air?

Maxine Whitely (52:58):

Throwing [crosstalk 00:52:59]?

Steph Coates (52:59):

Yeah.