The Bike Shed

Joël talks about his difficulties optimizing queries in ActiveRecord, especially with complex scopes and unions, resulting in slow queries. He emphasizes the importance of optimizing subqueries in unions to boost performance despite challenges such as query duplication and difficulty reusing scopes. Stephanie discusses upgrading a client's app to Rails 7, highlighting the importance of patience, detailed attention, and the benefits of collaborative work with a fellow developer. The conversation shifts to Ruby's reduce method (inject), exploring its complexity and various mental models to understand it. Joël and Stephanie discuss when it's preferable to use reduce over other methods like each, map, or loops and the importance of understanding the underlying operation you wish to apply to two elements before scaling up with reduce. The episode also touches on monoids and how they relate to reduce, suggesting that a deep understanding of functional programming concepts can help simplify reduce expressions. Rails 7 EXPLAIN ANALYZE (https://www.bigbinary.com/blog/rails-7-1-adds-options-to-activerecord-relation-explain) Blocks, symbol to proc, and symbols arguments for reduce (https://thoughtbot.com/blog/blocks-procs-and-enumerable) Ruby tally (https://medium.com/@baweaver/ruby-2-7-enumerable-tally-a706a5fb11ea) Performance considerations for reduce in JavaScript (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/Reduce#when_to_not_use_reduce) Persistant data structures (https://www.youtube.com/watch?v=gTClDj9Zl1g) Avoid passing a block to map and reduce (https://thoughtbot.com/blog/avoid-putting-logic-in-map-blocks) Functional Programming with Bananas, Lenses, Envelopes and Barbed Wire (https://ris.utwente.nl/ws/portalfiles/portal/6142049/meijer91functional.pdf) monoids (https://blog.ploeh.dk/2017/10/06/monoids/) iteration anti-patterns (https://thoughtbot.com/blog/iteration-as-an-anti-pattern) Joël’s talk on “constructor replacement” (https://www.youtube.com/watch?v=dSMB3rsufC8) Transcript:  STEPHANIE: Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Stephanie Minn. JOËL: And I'm Joël Quenneville. And together, we're here to share a bit of what we've learned along the way. STEPHANIE: So, Joël, what's new in your world? JOËL: I've been doing a bunch of fiddling with query optimization this week, and I've sort of run across an interesting...but maybe it's more of an interesting realization because it's interesting in the sort of annoying way. And that is that, using ActiveRecord scopes with certain more complex query pieces, particularly unions, can lead to queries that are really slow, and you have to rewrite them differently in a way that's not reusable in order to make them fast. In particular, if you have sort of two other scopes that involve joins and then you combine them using a union, you're unioning two sort of joins. Later on, you want to change some other scope that does some wares or something like that. That can end up being really expensive, particularly if some of the underlying tables being joined are huge. Because your database, in my case, Postgres, will pull a lot of this data into the giant sort of in-memory table as it's, like, building all these things together and to filter them out. And it doesn't have the ability to optimize the way it would on a more traditional relation. A solution to this is to make sure that the sort of subqueries that are getting unioned are optimized individually. And that can mean moving conditions that are outside the union inside. So, if I'm chaining, I don't know, where active is true on the outer query; on the union itself, I might need to move that inside each of the subqueries. So, now, in the two or three subqueries that I'm unioning, each of them needs to have a 'where active true' chained on it. STEPHANIE: Interesting. I have heard this about using ActiveRecord scopes before, that if the scopes are quite complex, chaining them might not lead to the most performant query. That is interesting. By optimizing the subqueries, did you kind of change the meaning of them? Was that something that ended up happening? JOËL: So, the annoying thing is that I have a scope that has the union in it, and it does some things sort of on its own. And it's used in some places. There are also other places that will try to take that scope that has the union on it, chain some other scopes that do other joins and some more filters, and that is horribly inefficient. So, I need to sort of rewrite the sort of subqueries that get union to include all these new conditions that only happen in this one use case and not in the, like, three or four others that rely on that union. So, now I end up with some, like, awkward query duplication in different call sites that I'm not super comfortable about, but, unfortunately, I've not found a good way to make this sort of nicely reusable. Because when you want to chain sort of more things onto the union, you need to shove them in, and there's no clean way of doing that. STEPHANIE: Yeah. I think another way I've seen this resolved is just writing it in SQL if it's really complex and it becoming just a bespoke query. We're no longer trying to use the scope that could be reusable. JOËL: Right. Right. In this case, I guess, I'm, like, halfway in between in that I'm using the ActiveRecord DSL, but I am not reusing scopes and things. So, I sort of have the, I don't know, naive union implementation that can be fine in all of the simpler use cases that are using it. And then the query that tries to combine the union with some other fancy stuff it just gets its own separate implementation different than the others that it has optimized. So, there are sort of two separate paths, two separate implementations. I did not drop down to writing raw SQL because I could use the ActiveRecord DSL. So, that's what I've been working with. What's new in your world this week? STEPHANIE: So, a couple of weeks ago, I think, I mentioned that I was working on a Rails 7 upgrade, and we have gotten it out the door. So, now the client application I'm working on is on Rails 7, which is exciting for the team. But in an effort to make the upgrade as incremental as possible, we did, like, back out of a few of the new application config changes that would have led us down a path of more work. And now we're kind of following up a little bit to try to turn some of those configs on to enable them. And it was very exciting to kind of, like, officially be on Rails 7. But I do feel like we tried to go for, like, the minimal amount of work possible in that initial big change. And now we're having to kind of backfill a little bit on some of the work that was a little bit more like, oh, I'm not really sure, like, how big this will end up being. And it's been really interesting work, I think, because it requires, like, two different mindsets. Like, one of them is being really patient and focused on tedious work. Like, okay, what happens when we enable this config option? Like, what changes? What errors do we see? And then having to turn it back off and then go in and fix them. But then another, I think, like, headspace that we have to be in is making decisions about what to do when we come to a crossroads around, like, okay, now that we are starting to see all the changes that are coming about from enabling this config, is this even what we want to do? And it can be really hard to switch between those two modes of thinking. JOËL: Yeah. How do you try to balance between the two? STEPHANIE: So, I luckily have been pairing with another dev, and I've actually found that to be really effective because he has, I guess, just, like, a little bit more of that patience to do the more tedious, mundane [laughs] aspects of, like, driving the code changes. And I have been riding along. But then I can sense, like, once he gets to the point of like, "Oh, I'm not sure if we should keep going down this road," I can step in a little bit more and be like, "Okay, like, you know, I've seen us do this, like, five times now, and maybe we don't want to do that." Or maybe being like, "Okay, we don't have a really clear answer, but, like, who can we talk to to find out a little bit more or get their input?" And that's been working really well for me because I've not had a lot of energy to do more of that, like, more manual or tedious labor [chuckles] that comes with working on that low level of stuff. So yeah, I've just been pleasantly surprised by how well we are aligning our superpowers. JOËL: To use some classic business speech, how does it feel to be in the future on Rails 7? STEPHANIE: Well, we're not quite up, you know, up to modern days yet, but it does feel like we're getting close. And, like, I think now we're starting to entertain the idea of, like, hmm, like, could we be even on main? I don't think it's really going to happen, but it feels a little bit more possible. And, in general, like, the team thinks that that could be, like, really exciting. Or it's easier, I think, once you're a little bit more on top of it. Like, the worst is when you get quite behind, and you end up just feeling like you're constantly playing catch up. It just feels a little bit more manageable now, which is good. JOËL: I learned this week a fun fact about Rails 7.1, in particular, which is that the analyze method on ActiveRecord queries, which allowed you to sort of get SQL EXPLAIN statements, now has the ability to pass in a couple of extra parameters. So, there are symbols, and you can pass in things like analyze or verbose, which allows you to get sort of more data out of your EXPLAIN query, which can be quite nice when you're debugging for performance. So, if you're in the future and you're on Rails 7.1 and you want sort of the in-depth query plans, you don't need to copy the SQL into a Postgres console to get access to the sort of fully developed EXPLAIN plan. You can now do it by passing arguments to EXPLAIN, which I'm very happy for. STEPHANIE: That's really nice. JOËL: So, we've mentioned before that we have a developers' channel on Slack here at thoughtbot, and there's all sorts of fun conversations that happen there. And there was one recently that really got me interested, where people were talking about Ruby's reduce method, also known as inject. And it's one of those methods that's kind of complicated, or it can be really confusing. And there was a whole thread where people were talking about different mental models that they had around the reduce method and how they sort of understand the way it works. And I'd be curious to sort of dig into each other's mental models of that today. To kick us off, like, how comfortable do you feel with Ruby's reduce method? And do you have any mental models to kind of hold it in your head? STEPHANIE: Yeah, I think reduce is so hard to wrap your head around, or it might be one of the most difficult, I guess, like, functions a new developer encounters, you know, in trying to understand the tools available to them. I always have to look up the order of the arguments [laughs] for reduce. JOËL: Every time. STEPHANIE: Yep. But I feel like I finally have a more intuitive sense of when to use it. And my mental model for it is collapsing a collection into one value, and, actually, that's why I prefer calling it reduce rather than the inject alias because reduce kind of signals to me this idea of going from many things to one canonical thing, I suppose. JOËL: Yeah, that's a very common use case for reducing, and I guess the name itself, reducing, kind of has almost that connotation. You're taking many things, and you're going to reduce that down to a single thing. STEPHANIE: What was really interesting to me about that conversation was that some people kind of had the opposite mental model where it made a bit more sense for them to think about injecting and, specifically, like, the idea of the accumulator being injected with values, I suppose. And I kind of realized that, in some ways, they're kind of antonyms [chuckles] a little bit because if you're focused on the accumulator, you're kind of thinking about something getting bigger. And that kind of blew my mind a little bit when I realized that, in some ways, they can be considered opposites. JOËL: That's really fascinating. It is really interesting, I think, the way that we can take the name of a method and then almost, like, tell ourselves a story about what it does that then becomes our way of remembering how this method works. And the story we tell for the same method name, or in this case, maybe there's a few different method names that are aliases, can be different from person to person. I know I tend to think of inject less in terms of injecting things into the accumulator and more in terms of injecting some kind of operator between every item in the collection. So, if we have an array of numbers and we're injecting plus, in my mind, I'm like, oh yeah, in between each of the numbers in the collection, just inject a little plus sign, and then do the math. We're summing all the items in the collection. STEPHANIE: Does that still hold up when the operator becomes a little more complex than just, you know, like, a mathematical operator, like, say, a function? JOËL: Well, when you start passing a block and doing custom logic, no, that mental model kind of falls apart. In order for it to work, it also has to be something that you can visualize as some form of infix operator, something that goes between two values rather than, like, a method name, which is typically in prefix position. I do want to get at this idea, though: the difference between sort of the block version versus passing. There are ways where you can just do a symbol, and that will call a method on each of the items. Because I have a bit of a hot take when it comes to writing reduce blocks or inject blocks that are more accessible, easier to understand. And that is, generally, that you shouldn't, or more specifically, you should not have a big block body. In general, you should be either using the symbol version or just calling a method within the block, and it's a one-liner. Which means that if you have some complex behavior, you need to find a way to move that out of this sort of collection operation and into instance methods on the objects being iterated. STEPHANIE: Hmm, interesting. By one-liner do you mean passing the name of the method as a proc or actually, like, having your block that then calls the method? Because I can see it becoming even simpler if you have already extracted a method. JOËL: Yeah, if you can do symbol to proc, that's amazing, or even if you can use just the straight-up symbol way of invoking reduce or inject. That typically means you have to start thinking about the types of objects that you are working with and what methods can be moved onto them. And sometimes, if you're working with hashes or something like that that don't have domain methods for what you want, that gets really awkward. And so, then maybe that becomes maybe a hint that you've got some primitive obsession happening and that this hash that sort of wants a domain object or some kind of domain method probably should be extracted to its own object. STEPHANIE: I'll do you with another kind of spicy take. I think, in that case, maybe you don't want a reduce at all. If you're starting to find that...well, okay, I think it maybe could depend because there could be some very, like, domain-specific logic. But I have seen reduce end up being used to transform the structure of the initial collection when either a different higher-order function can be used or, I don't know, maybe you're just better off writing it with a regular loop [laughs]. It could be clearer that way. JOËL: Well, that's really interesting because...so, you mentioned the idea that we could use a different higher-order function, and, you know, higher-order function is that fancy term, just a method that accepts another method as an argument. In Ruby, that just means your method accepts a block. Reduce can be used to implement pretty much the entirety of enumerable. Under the hood, enumerable is built in terms of each. You could implement it in terms of reduce. So, sometimes it's easy to re-implement one of the enumerable methods yourself, accidentally, using reduce. So, you've written this, like, complex reduce block, and then somebody in review comes and looks at it and is like, "Hey, you realize that's just map. You've just recreated map. What if we used map here?" STEPHANIE: Yeah. Another one I've seen a lot in JavaScript land where there are, you know, fewer utility functions is what we now have in Ruby, tally. I feel like that was a common one I would see a lot when you're trying to count instances of something, and I've seen it done with reduce. I've seen it done with a for each. And, you know, I'm sure there are libraries that actually provide a tally-like function for you in JS. But I guess that actually makes me feel even more strongly about this idea that reduce is best used for collapsing something as opposed to just, like, transforming a data structure into something else. JOËL: There's an interesting other mental model for reduce that I think is hiding under what we're talking about here, and that is the idea that it is a sort of mid-level abstraction for dealing with collections, as opposed to something like map or select or some of those other enumerable helpers because those can all be implemented in terms of reduce. And so, in many cases, you don't need to write the reduce because the library maintainer has already used reduce or something equivalent to build these higher-level helpers for you. STEPHANIE: Yeah, it's kind of in that weird point between, like, very powerful [chuckles] so that people can start to do some funky things with it, but also sometimes just necessary because it can feel a little bit more concise that way. JOËL: I've done a fair amount of functional programming in languages like Elm. And there, if you're building a custom data structure, the sort of lowest-level way you have of looping is doing a recursion, and recursions are messy. And so, what you can do instead as a library developer is say, "You know what, I don't want to be writing recursions for all of these." I don't know; maybe I'm building a tree library. I don't want to write a recursion for every different function that goes over trees if I want to map or filter or whatever. I'm going to write reduce using recursion, and then everything else can be written in terms of reduce. And then, if people want to do custom things, they don't need to recurse over my tree. They can use this reduce function, which allows them to do most of the traversals they want on the tree without needing to touch manual recursion. So, there's almost, like, a low-level, mid-level, high-level in the library design, where, like, lowest level is recursion. Ideally, nobody touches that. Mid-level, you've got reducing that's built out on top of recursion. And then, on top of that, you've got all sorts of other helpers, like mapping, like filtering, things like that. STEPHANIE: Hmm. I'm wondering, do you know of any performance considerations when it comes to using reduce built off a recursion? JOËL: So, one of the things that can be really nice is that writing a recursion yourself is dangerous. It's so easy to, like, accidentally introduce Stack Overflow. You could also write a really inefficient one. So, ideally, what you do is that you write a reduce that is safe and that is fast. And then, everybody else can just use that to not have to worry about the sort of mechanics of traversing the collection. And then, just use this. It already has all of the safety and speed features built in. You do have to be careful, though, because reduce, by nature, traverses the entire collection. And if you want to break out early of something expensive, then reduce might not be the tool for you. STEPHANIE: I was also reading a little bit about how, in JavaScript, a lot of developers like to stick to that idea of a pure function and try to basically copy the entire accumulator for every iteration and creating a new object for that. And that has led to some memory issues as well. As opposed to just mutating the accumulator, having, especially when you, you know, are going through a collection, like, really large, making that copy every single time and creating, yeah [chuckles], just a lot of issues that way. So, that's kind of what prompted that question. JOËL: Yeah, that can vary a lot by language and by data structure. In more functional languages that try to not mutate, they often have this idea of what they call persistent data structures, where you can sort of create copies that have small modifications that don't force you to copy the whole object under the hood. They're just, like, pointers. So, like, hey, we, like, are the same as this other object, but with this extra element added, or something like that. So, if you're growing an array or something like that, you don't end up with 10,000 copies of the array with, like, a new element every time. STEPHANIE: Yeah, that is interesting. And I feel like trying to adopt different paradigms for different tools, you know, is not always as straightforward as some wish it were [laughs]. JOËL: I do want to give a shout-out to an academic paper that is...it is infamously dense. The title of it is Functional Programming with Bananas, Lenses, and Barbed Wire. STEPHANIE: It doesn't sound dense; it sounds fun. Well, I don't about barbed wire. JOËL: It sounds fun, right? STEPHANIE: Yeah, but certainly quirky [laughs]. JOËL: It is incredibly dense. And they've, like, created this custom math notation and all this stuff. But the idea that they pioneered there is really cool, this idea that kind of like I was talking about sort of building libraries in different levels. Their idea is that recursion is generally something that's unsafe and that library and language designers should take care of all of the recursion and instead provide some of these sort of mid-level helper methods to do things. Reducing is one of them, but their proposal is that it's not the only one. There's a whole sort of family of similar methods that are there that would be useful in different use cases. So, reduce allows you to sort of traverse the whole thing. It does not allow you to break out early. It does not allow you to keep sort of track of a sort of extra context element if you want to, like, be traversing a collection but have a sort of look forward, look back, something like that. So, there are other variations that could handle those. There are variations that are the opposite of reduce, where you're, like, inflating, starting from a few parameters and building a collection out of them. So, this whole concept is called recursion schemes, and you can get, like, really deep into some theory there. You'll hear fancy words like catamorphisms and anamorphisms. There's a whole world to explore in that area. But at its core, it's this idea that you can sort of slice up things into this sort of low-level recursion, mid-level helpers, and then, like, kind of userland helpers built on top of that. STEPHANIE: Wow. That is very intense; it sounds like [chuckles]. I'm happy not to ever have to write a recursion ever again, probably [laughs]. Have you ever, as just a web developer in your day-to-day programming, found a really good use case for dropping down to that level? Or are you kind of convinced that, like, you won't really ever need to? JOËL: I think it depends on the paradigm of the language you're working in. In Ruby, I've very rarely needed to write a recursion. In something like Elm, I've had to do that, eh, not infrequently. Again, it depends, like, if I'm doing more library-esque code versus more application code. If I'm writing application code and I'm using an existing, let's say, tree library, then I typically don't need to write a recursion because they've already written traversals for me. If I'm making my own and I have made my own tree libraries, then yes, I'm writing recursions myself and building those traversals so that other people don't have to. STEPHANIE: Yeah, that makes sense. I'd much rather someone who has read that paper [laughs] write some traversal methods for me. JOËL: And, you know, for those who are curious about it, we will put a link to this paper in the description. So, we've talked about a sort of very academic mental model way of thinking about reducing. I want to shift gears and talk about one that I have found is incredibly practical, and that is the idea that reduce is a way to scale an operation that works on two objects to an operation that works on sort of an unlimited number of objects. To make it more concrete, take something like addition. I can add two numbers. The plus operator allows me to take one number, add another, get a sum. But what if I want to not just add two numbers? I want to add an arbitrary number of numbers together. Reduce allows me to take that plus operator and then just scale it up to as many numbers as I want. I can just plug that into, you know, I have an array of numbers, and I just call dot reduce plus operator, and, boom, it can now scale to as many numbers as I want, and I can sum the whole thing. STEPHANIE: That dovetails quite nicely with your take earlier about how you shouldn't pass a block to reduce. You should extract that into a method. Don't you think? JOËL: I think it does, yes. And then maybe it's, like, sort of two sides of a coin because I think what this leads to is an approach that I really like for reducing because sometimes, you know, here, I'm starting with addition. I'm like, oh, I have addition. Now, I want to scale it up. How do I do that? I can use reduce. Oftentimes, I'm faced with sort of the opposite problem. I'm like, oh, I need to add all these numbers together. How do I do that? I'm like, probably with a reduce. But then I start writing the block, and, like, I get way too into my head about the accumulator and what's going to happen. So, my strategy for writing reduce expressions is to, instead of trying to figure out how to, like, do the whole thing together, first ask myself, how do I want to combine any two elements that are in the array? So, I've got an array of numbers, and I want to sum them all. What is the thing I need to do to combine just two of those? Forget the array. Figure that out. And then, once I have that figured out, maybe it's an existing method like plus. Maybe it's a method I need to define on it if it's a custom object. Maybe it's a method that I write somewhere. Then, once I have that, I can say, okay, I can do it for two items. Now, I'm going to scale it up to work for the whole array, and I can plug it into reduce. And, at that point, the work is already basically done, so I don't end up with a really complex block. I don't end up, like, almost ending in, like, a recursive infinite loop in my head because I do that. STEPHANIE: [laughs]. JOËL: So, that approach of saying, start by figuring out what is the operation you want to do to combine two elements, and then use reduce as a way to scale that to your whole array is a way that I've used to keep things simple in my mind. STEPHANIE: Yeah, I like that a lot as a supplement to the model I shared earlier because, for me, when I think about reducing as, like, collapsing into a value, you kind of are just like, well, okay, I start with the collection, and then somehow I get to my single value. But the challenge is figuring out how that happens [laughs], like, the magic that happens in between that. And I think another alias that we haven't mentioned yet for reduce that is used in a lot of other languages is fold. And I actually like that one a lot, and I think it relates to your mental model. Because when I think about folding, I'm picturing folding up a paper like an accordion. And you have to figure out, like, what is the first fold that I can make? And just repeating that over and over to get to your little stack of accordion paper [laughs]. And if you can figure out just that first step, then you pretty much, like, have the recipe for getting from your initial input to, like, your desired output. JOËL: Yeah. I think fold is interesting in that some languages will make a distinction between fold and reduce. They will have both. And typically, fold will require you to pass an initial value, like a starting accumulator, to start it off. Whereas reduce will sort of assume that your array can use the first element of the array as the first accumulator. STEPHANIE: Oh, I just came up with another visual metaphor for this, which is, like, folding butter into croissant pastry when the butter is your initial value [laughs]. JOËL: And then the crust is, I guess, the elements in the array. STEPHANIE: Yeah. Yeah. And then you get a croissant out of it [laughs]. Don't ask me how it gets to a perfectly baked, flaky, beautiful croissant, but somehow that happens [laughs]. JOËL: So, there's an interesting sort of subtlety here that I think happens because there are sort of two slightly different ways that you can interact with a reduce. Sometimes, your accumulator is of the same type as the elements in your array. So, you're summing an array of numbers, and your accumulator is the sum, but each of the elements in the array are also numbers. So, it's numbers all the way through. And sometimes, your accumulator has a different type than the items in the array. So, maybe you have an array of words, and you want to get the sum of all of the characters and all the words. And so, now your accumulator is a number, but each of the items in the array are strings. STEPHANIE: Yeah, that's an interesting distinction because I think that's where you start to see the complex blocks being passed and reduced. JOËL: The complex blocks, definitely; I think they tend to show up when your accumulator has a different type than the individual items. So, maybe that's, like, a slightly more complicated use case. Oftentimes, too, the accumulator ends up being some, like, more complex, like, hash or something that maybe would really benefit from being a custom object. STEPHANIE: I've never done that before, but I can see why that would be really useful. Do you have an example of when you used a custom object as the accumulator? JOËL: So, I've done it for situations where I'm working with objects that are doing tally-like operations, but I'm not doing just a generic tally. There's some domain-specific stuff happening. So, it's some sort of aggregate counter on multiple dimensions that you can use, and that can get really ugly. And you can either do it with a reduce or you can have some sort of, like, initial version of the hash outside and do an each and mutate the hash and stuff like that. All of these tend to be a little bit ugly. So, in those situations, I've often created some sort of custom object that has some instance methods that allow to sort of easily add new elements to it. STEPHANIE: That's really interesting because now I'm starting to think, what if the elements in the collection were also a custom object? [chuckles] And then things could, I feel like, could be really powerful [laughs]. JOËL: There's often a lot of value, right? Because if the items in the collection are also a custom object, you can then have methods on them. And then, again, the sort of complexity of the reduce can sort of, like, fade away because it doesn't own any of the logic. All it does is saying, hey, there's a thing you can do to combine two items. Let's scale it up to work on a collection of items. And now you've sort of, like, really simplified what logic is actually owned inside the reduce. I do want to shout out for those listeners who are theory nerds and want to dig into this. When you have a reduce, and you've got an operation where all the values are of the same type, including the accumulator, typically, what you've got here is some form of monoid. It may be a semigroup. So, if you want to dig into some theory, those are the words to Google and to go a deep dive on. The main thing about monoids, in particular, is that monoids are any objects that have both a sort of a base case, a sort of empty version of themselves, and they have some sort of combining method that allows you to combine two values of that type. If your object has these things and follows...there's a few rules that have to be true. You have a monoid. And they can then be sort of guaranteed to be folded nicely because you can plug in their base case as your initial accumulator. And you can plug in their combining method as just the value of the block, and everything else just falls into place. A classic here is addition for numbers. So, if you want to add two numbers, your combining operator is a plus. And your sort of empty value is a zero. So, you would say, reduce initial value is zero, array of numbers. And your block is just plus, and it won't sum all of the numbers. You could do something similar with strings, where you can combine strings together with plus, and, you know, your empty string is your base case. So, now you're doing sort of string concatenation over arbitrary number of strings. Turns out there's a lot of operations that fall into that, and you can even define some of those on your custom object. So, you're like, oh, I've got a custom object. Maybe I want some way of, like, combining two of them together. You might be heading in the direction of doing something that is monoidal, and if so, that's a really good hint to know that it can sort of, like, just drop into place with a fold or a reduce and that that is a tool that you have available to you. STEPHANIE: Yeah, well, I think my eyes, like, widened a little bit when you first dropped the term monoid [laughs]. I do want to spend the last bit of our time talking about when not to use reduce, and, you know, we did talk a lot about recursion. But when do you think a regular old loop will just be enough? JOËL: So, you're suggesting when would you want to use something like an each rather than a reduce? STEPHANIE: Yeah. In my mind, you know, you did offer, like, a lot of ways to make reduce simpler, a lot of strategies to end up with some really nice-looking syntax [chuckles], I think. But, oftentimes, I think it can be equally as clear storing your accumulator outside of the iteration and that, like, is enough for me to understand. And reduce takes a little bit of extra overhead to figure out what I'm looking at. Do you have any thoughts about when you would prefer to do that? Or do you think that you would usually reach for something else? JOËL: Personally, I generally don't like the pattern of using each to iterate over a collection and then mutate some external accumulator. That, to me, is a bit of a code smell. It's a sign that each is not quite powerful enough to do the thing that I want to do and that I'm probably needing some sort of more specialized form of iteration. Sometimes, that's reduce. Oftentimes, because each can suffer from the same problem you mentioned from reduce, where it's like, oh, you're doing this thing where you mutate an external accumulator. Turns out what you're really doing is just map. So, use map or use select or, you know, some of the other built-in iterators from the enumerable library. There's a blog post on the thoughtbot blog that I continually link to people. And when I see the pattern of, like, mutating an external variable with each, yeah, I tend to see that as a bit of a code smell. I don't know that I would never do it, but whenever I see that, it's a sign to me to, like, pause and be like, wait a minute, is there a better way to do this? STEPHANIE: Yeah, that's fair. I like the idea that, like, if there's already a method available to you that is more specific to go with that. But I also think that sometimes I'd rather, like, come across that pattern of mutating a variable outside of the iteration over, like, someone trying to do something clever with the reduce. JOËL: Yeah, I guess reduce, especially if it's got, like, a giant block and you've got then, like, things in there that break or call next to skip iterations and things like that, that gets really mind-bending really quickly. I think a case where I might consider using an each over a reduce, and that's maybe generally when I tend to use each, is when I'm doing side effects. If I'm using a reduce, it's because I care about the accumulated value at the end. If I'm using each, it's typically because I am trying to do some amount of side effects. STEPHANIE: Yeah, that's a really good call out. I had that written down in my notes, and I'm glad you brought it up because I've seen them get conflated a little bit, and perhaps maybe that's the source of the pain that I'm talking about. But I really like that heuristic of reduce as, you know, you're caring about the output, as opposed to what's going on inside. Like, you don't want any unexpected behavior. JOËL: And I think that applies to something like map as well. My sort of heuristic is, if I'm doing side effects, I want each. If I want transformed values that are sort of one-to-one in the collection, I want map. If I want a single sort of aggregate value, then I want reduce. STEPHANIE: I think that's the cool thing about mixing paradigms sometimes, where all the strategies you talked about in terms of, you know, using custom, like, objects for your accumulator, or the elements in your collection, like, that's something that we get because, you know, we're using an object-oriented language like Ruby. But then, like, you also are kind of bringing the functional programming lens to, like, when you would use reduce in the first place. And yeah, I am just really excited now [chuckles] to start looking for some places I can use reduce after this conversation and see what comes out of it. JOËL: I think I went on a bit of an interesting journey where, as a newer programmer, reduce was just, like, really intense. And I struggled to understand it. And I was like, ban it from code. I don't want to ever see it. And then, I got into functional programming. I was like, I'm going to do reduce everywhere. And, honestly, it was kind of messy. And then I, like, went really deep on a lot of functional theory, and I think understood some things that then I was able to take back to my code and actually write reduce expressions that are much simpler so that now my heuristic is like, I love reduce; I want to use it, but I want as little as possible in the reduce itself. And because I understand some of these other concepts, I have the ability to know what things can be extracted in a way that will feel very natural, in a way that myself from five years ago would have just been like, oh, I don't know. I've got this, you know, 30-line reduce expression that I know is complicated, but I don't know how to improve. And so, a little bit of the underlying theory, I don't think it's necessary to understand these simplified reduces, but as an author who's writing them, I think it helps me write reduces that are simpler. So, that's been my journey using reduce. STEPHANIE: Yeah. Well, thanks for sharing. And I'm really excited. I hope our listeners have learned some new things about reduce and can look at it from a different light. JOËL: There are so many different perspectives. And I think we keep discovering new mental models as we talk to different people. It's like, oh, this particular perspective. And there's one that we didn't really dig into but that I think makes more sense in a functional world that's around sort of deconstructing a structure and then rebuilding it with different components. The shorthand name of this mental model, which is a fairly common one, is constructor replacement. For anyone who's interested in digging into that, we'll link it in the show notes. I gave a talk at an Elm meetup where I sort of dug into some of that theory, which is really interesting and kind of mind-blowing. Not as relevant, I think, for Rubyists, but if you're in a language that particularly allows you to build custom structures out of recursive types or what are sometimes called algebraic data types, or tagged unions, or discriminated unions, this thing goes by a bajillion names, that is a really interesting other mental model to look at. And, again, I don't think the list that we've covered today is exhaustive. You know, I would love it for any of our listeners; if you have your own mental models for how to think about folding, injecting, reducing, send them in: hosts@bikeshed.fm. We'd love to hear them. STEPHANIE: And on that note, shall we wrap up? JOËL: Let's wrap up. STEPHANIE: Show notes for this episode can be found at bikeshed.fm. JOËL: This show has been produced and edited by Mandy Moore. STEPHANIE: If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter. STEPHANIE: Or reach both of us at hosts@bikeshed.fm via email. JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week. ALL: Byeeeeeeee!!!!!!! AD: Did you know thoughtbot has a referral program? If you introduce us to someone looking for a design or development partner, we will compensate you if they decide to work with us. More info on our website at: tbot.io/referral. Or you can email us at referrals@thoughtbot.com with any questions.

Stephanie shares about her vacation at Disney World, particularly emphasizing the technological advancements in the park's mobile app that made her visit remarkably frictionless. Joël had a conversation about a topic he loves: units of measure, and he got to go deep into the idea of dimensional analysis with someone this week. Together, Joël and Stephanie talk about module documentation within software development. Joël shares his recent experience writing module docs for a Ruby project using the YARD documentation system. He highlights the time-consuming nature of crafting good documentation for each public method in a class, emphasizing that while it's a demanding task, it significantly benefits those who will use the code in the future. They explore the attributes of good documentation, including providing code examples, explaining expected usage, suggesting alternatives, discussing edge cases, linking to external resources, and detailing inputs, outputs, and potential side effects. Multidimensional numbers episode (https://bikeshed.thoughtbot.com/416) YARD docs (https://yardoc.org/) New factory_bot documentation (https://thoughtbot.com/blog/new-docs-for-factory_bot) Dash (https://kapeli.com/dash) Solargraph (https://solargraph.org/) Transcript:  JOËL: Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Joël Quenneville. STEPHANIE: And I'm Stephanie Minn, and together, we're here to share a bit of what we've learned along the way. JOËL: So, Stephanie, what's new in your world? STEPHANIE: So, I recently was on vacation, and I'm excited [chuckles] to tell our listeners all about it. I went to Disney World [laughs]. And honestly, I was especially struck by the tech that they used there. As a person who works in tech, I always kind of have a little bit of a different experience knowing a bit more about software, I suppose, than just your regular person [laughs], citizen. And so, at Disney World, I was really impressed by how seamlessly the like, quote, unquote, "real life experience" integrated with their use of their branded app to pair with, like, your time at the theme park. JOËL: This is, like, an app that runs on your mobile device? STEPHANIE: Yeah, it's a mobile app. I haven't been to Disney in a really long time. I think the last time I went was just as a kid, like, this was, you know, pre-mobile phones. So, I recall when you get into the line at a ride, you can skip the line by getting what's called a fast pass. And so, you kind of take a ticket, and it tells you a designated time to come back so that you could get into the fast line, and you don't have to wait as long. And now all this stuff is on your mobile app, and I basically did not wait in [laughs] a single line for more than, like, five minutes to go on any of the rides I wanted. It just made a lot of sense that all these things that previously had more, like, physical touchstones, were made a bit more convenient. And I hesitate to use the word frictionless, but I would say that accurately describes the experience. JOËL: That's kind of amazing; the idea that you can use tech to make a place that's incredibly busy also feel seamless and where you don't have to wait in line. STEPHANIE: Yeah and, actually, I think the coolest part was it blended both your, like, physical experience really well with your digital one. I think that's kind of a gripe I have as a technologist [laughs] when I'm just kind of too immersed in my screen as opposed to the world around me. But I was really impressed by the way that they managed to make it, like, a really good supplement to your experience being there. JOËL: So, you're not hyped for a future world where you can visit Disney in VR? STEPHANIE: I mean, I just don't think it's the same. I rode a ride [laughs] where it was kind of like a mini roller coaster. It was called Expedition Everest. And there's a moment, this is, like, mostly indoors, but there's a moment where the roller coaster is going down outside, and you're getting that freefall, like, drop feeling in your stomach. And it also happened to be, like, drizzling that day that we were out there, and I could feel it, you know, like, pelting my head [laughs]. And until VR can replicate that experience [chuckles], I still think that going to Disney is pretty fun. JOËL: Amazing. STEPHANIE: So, Joël, what's new in your world? JOËL: I'm really excited because I had a conversation about a topic that I like to talk about: units of measure. And I got to go deep into the idea of dimensional analysis with someone this week. This is a technique where you can look at a calculation or a function and sort of spot-check whether it's correct by looking at whether the unit for the measure that would come out match what you would expect. So, you do math on the units and ignore the numbers coming into your formula. And, you know, let's say you're calculating the speed of something, and you get a distance and the amount of time it took you to take to go that distance. And let's say your method implements this as distance times time. Forget about doing the actual math with the numbers here; just look at the units and say, okay, we've got our meters, and we've got our seconds, and we're multiplying them together. The unit that comes out of this method is meters times seconds. You happen to know that speeds are not measured in meters times seconds. They're measured in meters divided by seconds or meters per second. So, immediately, you get a sense of, like, wait a minute, something's wrong here. I must have a bug in my function. STEPHANIE: Interesting. I'm curious how you're representing that data to, like, know if there's a bug or not. In my head, when you were talking about that, I'm like, oh yeah, I definitely recall doing, like, math problems for homework [laughs] where I had, you know, my meters per second. You have your little fractions written out, and then when you multiply or divide, you know how to, like, deal with the units on your piece of paper where you're showing your work. But I'm having a hard time imagining what that looks like as a programmer dealing with that problem. JOËL: You could do it just all in your head based off of maybe some comments that you might have or the name of the variable or something. So, you're like, okay, well, I have a distance in meters and a time in seconds, and I'm multiplying the two. Therefore, what should be coming out is a value that is in meters times seconds. If you want to get fancier, you can do things with value objects of different types. So, you say, okay, I have a distance, and I have a time. And so, now I have sort of a multiplication of a distance and a time, and sort of what is that coming out as? That can sometimes help you prevent from having some of these mistakes because you might have some kind of error that gets raised at runtime where it's like, hey, you're trying to multiply two units that shouldn't be multiplied, or whatever it is. You can also, in some languages, do this sort of thing automatically at the type level. So, instead of looking at it yourself and sort of inferring it all on your own based off of the written code, languages like F# have built-in unit-of-measure systems where once you sort of tag numbers as just being of a particular unit of measure, any time you do math with those numbers, it will then tag the result with whatever compound unit comes from that operation. So, you have meters, and you have seconds. You divide one by the other, and now the result gets tagged as meters per second. And then, if you have another calculation that takes the output of the first one and it comes in, you can tell the compiler via type signature, hey, the input for this method needs to be in meters per second. And if the other calculation sort of automatically builds something that's of a different unit, you'll get a compilation error. So, it's really cool what it can do. STEPHANIE: Yeah, that is really neat. I like all of those built-in guardrails, I suppose, to help you, you know, make sure that your answer is correct. Definitely could have used that [chuckles]. Turns out I just needed a calculator to take my math test with [laughs]. JOËL: I think what I find valuable more than sort of the very rigorous approach is the mindset. So, anytime you're dealing with numbers, thinking in your mind, what is the unit of this number? When I do math with it with a different number, is it the same unit? Is it a different unit? What is the unit of the thing that's coming out? Does this operation make sense in the domain of my application? Because it's easy to sometimes think you're doing a math operation that makes sense, and then when you look at the unit, you're like, wait a minute, this does not make sense. And I would go so far as to say that, you know, you might think, oh, I'm not doing a physics app. I don't care about units of measure. Most numbers in your app that are actually numbers are going to have some kind of unit of measure associated to them. Occasionally, you might have something where it's just, like, a straight-up, like, quantity or something like that. It's a dimensionless number. But most things will have some sort of unit. Maybe it's a number of dollars. Maybe it is an amount of time, a duration. It could be a distance. It could be all sorts of things. Typically, there is some sort of unit that should attach to it. STEPHANIE: Yeah. That makes sense that you would want to be careful about making sure that your mathematical operations that you're doing when you're doing objects make sense. And we did talk about this in the last episode about multidimensional numbers a little bit. And I suppose I appreciate you saying that because I think I have mostly benefited from other people having thought in that mindset before and encoding, like I mentioned, those guardrails. So, I can recall an app where I was working with, you know, some kind of currency or money object, and that error was raised when I would try to divide by zero because rather than kind of having to find out later with some, not a number or infinite [laughs] amount of money bug, it just didn't let me do that. And that wasn't something that I had really thought about, you know, I just hadn't considered that zero value edge case when I was working on whatever feature I was building. JOËL: Yeah, or even just generally the idea of dividing money. What does that even mean? Are you taking an amount of money and splitting it into two equivalent piles to split among multiple people? That kind of makes sense. Are you dividing money by another money value? That's now asking a very different kind of question. You're asking, like, what is the ratio between these two, I guess, piles of money if we want to make it, you know, in the physical world? Is that a thing that makes sense in your application? But also, realize that that ratio that you get back is not itself an amount of money. And so, there are some subtle bugs that can happen around that when you don't keep track of what your quantities are. So, this past week, I've been working on a project where I ended up having to write module docs for the code in question. This is a Ruby project, so I'm writing docs using the YARD documentation system, where you effectively just write code comments at the sort of high level covering the entire class and then, also, individual documentation comments on each of the methods. And that's been really interesting because I have done this in other languages, but I'd never done it in Ruby before. And this is a piece of code that was kind of gnarly and had been tricky for me to figure out. And I figured that a couple of these classes could really benefit from some more in-depth documentation. And I'm curious, in your experience, Stephanie, as someone who's writing code, using code from other people, and who I assume occasionally reads documentation, what are the things that you like to see in good sort of method-level docs? STEPHANIE: Personally, I'm really only reading method-level docs when, you know, at this point, I'm, like, reaching for a method. I want to figure out how to use it in my use case right now [laughs]. So, I'm going to search API documentation for it. And I really am just scanning for inputs, especially, I think, and maybe looking at, you know, some potential various, like, options or, like, variations of how to use the method. But I'm kind of just searching for that at a glance and then moving on [laughs] with my day. That is kind of my main interaction with module docs like that, and especially ones for Ruby and Rails methods. JOËL: And for clarity's sake, I think when we're talking about module docs here, I'm generally thinking of, like, any sort of documentation that sort of comments in code meant to document. It could be the whole modular class. It could be on a per-method level, things like RDoc or YARD docs on Ruby classes. You used the word API docs here. I think that's a pretty similar idea. STEPHANIE: I really haven't given the idea of writing this kind of documentation a lot of thought because I've never had to do too much of it before, but I know, recently, you have been diving deep into it because, you know, like you said, you found these classes that you were working with a bit ambiguous, I suppose, or just confusing. And I'm wondering what kind of came out of that journey. What are some of the most interesting aspects of doing this exercise? JOËL: And one of the big ones, and it's not a fun one, but it is time-consuming. Writing good docs per method for a couple of classes takes a lot of time, and I understand why people don't do it all the time. STEPHANIE: What kinds of things were you finding warranted that time? Like, you know, you had to, at some point, decide, like, whether or not you're going to document any particular method. And what were some of the things you were looking out for as good reasons to do it? JOËL: I was making the decisions to document or not document on a class level, and then every public method gets documentation. If there's a big public API, that means every single one of those methods is getting some documentation comments, explaining what they do, how they're meant to be used, things like that. I think my kind of conclusion, having worked with this, is that the sort of sweet spot for this sort of documentation is for anything that is library-like, so a lot of things that maybe would go into a Rails lib directory might make sense. Anything you're turning into a gem that probably makes sense. And sometimes you have things in your Rails codebase that are effectively kind of library-like, and that was the case for the code that I was dealing with. It was almost like a mini ORM style kind of ActiveRecord-inspired series of base classes that had a bunch of metaprogramming to allow you to write models that were backed by not a database but a headless CMS, a content management system. And so, these classes are not extracted to the lib directory or, like, made into a gem, but they feel very library-esque in that way. STEPHANIE: Library-like; I like that descriptor a lot because it immediately made me think of another example of a time when I've used or at least, like, consumed this type of documentation in a, like, SaaS repo. Rather, you know, I'm not really seeing that level of documentation around domain objects, but I noticed that they really did a lot of extending of the application record class because they just had some performance needs that they needed to write some, like, custom code to handle. And so, they ended up kind of writing a lot of their own ORM-like methods for just some, like, custom callbacks on persisting and some just, like, bulk insertion functionality. And those came with a lot of different ways to use them. And I really appreciated that they were heavily documented, kind of like you would expect those ActiveRecord methods to be as well. JOËL: So, I've been having some conversations with other members at thoughtbot about when they like to use the style of module doc. What are some of the alternatives? And one that kept coming up for different people that they would contrast with this is what they would call the big README approach, and this could be for a whole gem, or it could be maybe some directory with a few classes in your application that's got a README in the root of the directory. And instead of documenting each method, you just write a giant README trying to answer sort of all of the questions that you anticipate people will ask. Is that something that you've seen, and how do you feel about that as a tool when you're looking for help? STEPHANIE: Yes. I actually really like that style of documentation. I find that I just want examples to get me started, especially; I guess this is especially true for libraries that I'm not super familiar with but need to just get a working knowledge about kind of immediately. So, I like to see examples, the getting started, the just, like, here's what you need to know. And as I start to use them, that will get me rolling. But then, if I find I need more details, then I will try to seek out more specific information that might come in the form of class method documentation. But I'm actually thinking about how FactoryBot has one of the best big README-esque [laughs] style of documentation, and I think they did a really big refresh of the docs not too long ago. It has all that high-level stuff, and then it has more specific information on how to use, you know, the most common methods to construct your factories. But those are very detailed, and yet they do sit, like, separately from inline, like, code documentation in the style of module docs that we're talking about. So, it is kind of an interesting mix of both that I think is helpful for me personally when I want both the “what do I need to know now?” And the, “like, okay, I know where to look for if I need something a little more detailed.” JOËL: Yeah. The two don't need to be mutually exclusive. I thought it was interesting that you mentioned how much examples are valuable to you because...I don't know if this is controversial, but an opinion that I have about sort of per-method documentation is that you should always default to having a code example for every method. I don't care how simple it is or how obvious it is what it does. Show me a code example because, as a developer, examples are really, really helpful. And so, seeing that makes documentation a lot more valuable than just a couple of lines that explain something that was maybe already obvious from the title of the method. I want to see it in action. STEPHANIE: Interesting. Do you want to see it where the method definition is? JOËL: Yes. Because sometimes the method definition, like, the implementation, might be sort of complex. And so, just seeing a couple of examples, like, oh, you call with this input, you get that. Call with this other input; you get this other thing. And we see this in, you know, some of the core docs for things like the enumerable methods where having an example there to be like, oh, so that's how map works. It returns this thing under these circumstances. That sort of thing is really helpful. And then, I'll try to do it at a sort of a bigger level for that class itself. You have a whole paragraph about here's the purpose of the class. Here's how you should use it. And then, here's an example of how you might use it. Particularly, if this is some sort of, like, base class you're meant to inherit from, here's the circumstances you would want to subclass this, and then here's the methods you would likely want to override. And maybe here are the DSLs you might want to have and to kind of package that in, like, a little example of, in this case, if you wanted a model that read from the headless CMS, here's what an example of such a little model might look like. So, it's kind of that putting it all together, which I think is nice in the module docs. It could probably also live in the big README at some level. STEPHANIE: Yeah. As you are saying that, I also thought about how I usually go search for tests to find examples of usage, but I tend to get really overwhelmed when I see inline, like, that much inline documentation. I have to, like, either actively ignore it, choose to ignore it, or be like, okay, I'm reading this now [laughs]. Because it just takes up so much visual space, honestly. And I know you put a lot of work into it, a lot of time, but maybe it's because of the color of my editor theme where comments are just that, like, light gray [laughs]. I find them quite easy to just ignore. But I'm sure there will be some time where I'm like, okay, like, if I need them, I know they're there. JOËL: Yeah, that is, I think, a downside, right? It makes it harder to browse the code sometimes because maybe your entire screen is almost taken up by documentation, and then, you know, you have one method up, and you've got to, like, scroll through another page of documentation before you hit the next method, and that makes it harder to browse. And maybe that's something that plays into the idea of that separation between library-esque code versus application code. When you browse library-esque code, when you're actually browsing the source, you're probably doing it for different reasons than you would for code in your application because, at that point, you're effectively source diving, sometimes being like, oh, I know this class probably has a method that will do the thing I want. Where is it? Or you're like, there's an edge case I don't understand on this method. I wonder what it does. Let me look at the implementation. Or even some existing code in the app is using this library method. I don't know what it does, but they call this method, and I can't figure out why they're using it. Let me look at the source of the library and see what it does under the hood. STEPHANIE: Yeah. I like the distinction of it is kind of a different mindset that you're reading the code at, where, like, sometimes my brain is already ready to just read code and try to figure out inputs and outputs that way. And other times, I'm like, oh, like, I actually can't parse this right now [chuckles]. Like, I want to read just English, like, telling me what to expect or, like, what to look out for, especially when, like you said, I'm not really, like, trying to figure out some strange bug that would lead me to diving deep in the source code. It's I'm at the level where I'm just reaching for a method and wanting to use it. We're writing these YARD docs. I think I also heard you mention that you gave some, like, tips or maybe some gotchas about how to use certain methods. I'm curious why that couldn't have been captured in a more, like, self-documenting way. Or was there a way that you could have written the code for that not to have been needed as a comment or documented as that? And was there a way that method names could have been clear to signal, like, the intention that you were trying to convey through your documentation? JOËL: I'm a big fan of using method names as a form of documentation, but they're frequently not good enough. And I think comments, whether they're just regular inline comments or more official documentation, can be really good to help avoid sort of common pitfalls. And one that I was working with was, there were two methods, and one would find by a UID, so it would search up a document by UID. And another one would search by ID. And when I was attempting to use these before I even started documenting, I used the wrong one, and it took me a while to realize, oh wait, these things have both UIDs and IDs, and they're slightly different, and sometimes you want to use one or the other. The method names, you know, said like, "Find by ID" or "Find by UID." I didn't realize there were both at the time because I wasn't browsing the source. I was just seeing a place where someone had used it. And then, when I did find it in the source, I'm like, well, what is the difference? And so, something that I did when I wrote the docs was sort of call out on both of those methods; by the way, there is also find by UID. If you're searching by UID, consider using the other one. If you don't know what the difference is, here's a sentence summarizing the difference. And then, here's a link to external documentation if you want to dive into the nitty gritty of why there are two and what the differences are. And I think that's something you can't capture in just a method name. STEPHANIE: Yeah, that's true. I like that a lot. Another use case you can think of is when method names are aliased, and it's like, I don't know how I would have possibly known that until I, you know, go through the journey of realizing [laughs] that these two methods do the same thing or, like, stumbling upon where the aliasing happens. But if that were captured in, like, a little note when I'm in, like, a documentation viewer or something, it's just kind of, like, a little tidbit of knowledge [laughs] that I get to gain along the way that ends up, you know, being useful later because I will have just kind of...I will likely remember having seen something like that. And I can at least start my search with a little bit more context than when you don't know what you don't know. JOËL: I put a lot of those sorts of notes on different methods. A lot of them are probably based on a personal story where I made a mistaken assumption about this method, and then it burned me. But I'm like, okay, nobody else is going to make that mistake. By the way, if you think this is what the method does, it does something slightly different and, you know, here's why you need to know that. STEPHANIE: Yeah, you're just looking out for other devs. JOËL: And, you know, trying to, like, take my maybe negative experience and saying like, "How can I get value out of that?" Maybe it doesn't feel great that I lost an hour to something weird about a method. But now that I have spent that hour, can I get value out of it? Is the sort of perspective I try to have on that. So, you mentioned kind of offhand earlier the idea of a documentation viewer, which would be separate than just reading these, I guess, code comments directly in your code editor. What sort of documentation viewers do you like to use? STEPHANIE: I mostly search in my browser, you know, just the official documentation websites for Rails, at least. And then I know that there are also various options for Ruby as well. And I think I had mentioned it before but using DuckDuckGo as my search engine. I have nice bang commands that will just take me straight to the search for those websites, which is really nice. Though, I have paired with people before who used various, like, macOS applications to do something similar. I think Alfred might have some built-in workflows for that. And then, a former co-worker used to use one called Dash, that I have seen before, too. So, it's another one of those just handy just, like, search productivity extensions. JOËL: You mentioned the Rails documentation, and this is separate from the guides. But the actual Rails docs are generated from comments like this inline in code. So, all the different ActiveRecord methods, when you search on the Rails documentation you're like, oh yeah, how does find_by work? And they've got a whole, like, paragraph explaining how it works with a couple of examples. That's this kind of documentation. If you open up that particular file in the source code, you'll find the comments. And it makes sense for Rails because Rails is more of, you know, library-esque code. And you and I search these docs pretty frequently, although we don't tend to do it, like, by opening the Rails gem and, like, grepping through the source to find the code comment. We do it through either a documentation site that's been compiled from that source or that documentation that's been extracted into an offline tool, like you'd mentioned, Dash. STEPHANIE: Yeah, I realized how conflicting, I suppose, it is for me to say that I find inline documentation really overwhelming or visually distracting, whereas I recognize that the only reason I can have that nice, you know, viewing experience is because documentation viewers use the code comments in that format to be generated. JOËL: I wonder if there's like a sort of...I don't know what this pattern is called, but a bit of a, like, middle-quality trap where if you're going to source dive, like, you'd rather just look at the code and not have too much clutter from sort of mediocre comments. But if the documentation is really good and you have the tooling to read it, then you don't even need to source dive at all. You can just read the documentation, and that's sufficient. So, both extremes are good, but that sort of middle kind of one foot in each camp is sort of the worst of both worlds experience. Because I assume when you look for Rails documentation, you never open up the actual codebase to search. The documentation is good enough that you don't even need to look at the files with the comments and the code. STEPHANIE: Yeah, and I'm just recalling now there's, like, a UI feature to view the source from the documentation viewer page. JOËL: Yes. STEPHANIE: I use that actually quite a bit if the comments are a little bit sparse and I need just the code to supplement my understanding, and that is really nice. But you're right, like, I very rarely would be source diving, unless it's a last resort [laughs], let's be honest. JOËL: So, we've talked about documentation viewers and how that can make things nice, and you're able to read documentation for things. But a lot of other tooling can benefit from this sort of model documentation as well, and I'm thinking, in particular, Solargraph, which is Ruby's language server protocol. And it has plugins for VS Code, for Vim, for a few different editors, takes advantage of that to provide all sorts of things. So, you can get smart expansion of code and good suggestions. You can get documentation for what's under your cursor. Maybe you're reading somebody else's code that they've written, and you're like, why are they calling this parameterized method here? What does that even do? Like, in VS Code, you could just hover over it, and it will pop up and show you documentation, including the, like, inputs and return types, and things like that. That's pretty nifty. STEPHANIE: Yeah, that is cool. I use VS Code, but I've not seen that too much yet because I don't think I've worked in enough codebases with really comprehensive [laughs] YARD docs. I'm actually wondering, tooling-wise, did you use any helpful tools when you were writing them or were you hand-documenting each? JOËL: I was hand-documenting everything. STEPHANIE: Class. Okay. JOËL: The thing that I did use is the YARD gem, which you don't need to have the gem to write YARD-style documentation. But if you have the gem, you can run a local server and then preview a documentation site that is generated from your comments that has everything in there. And that was incredibly helpful for me as I was trying to sort of see an overview of, okay, what would someone who's looking at the docs generated from this see when they're trying to look for what the documentation of a particular method does? STEPHANIE: Yeah, and that's really nice. JOËL: Something that I am curious about that I've not really had a lot of experience with is whether or not having extra documentation like that can help AI tools give us better suggestions. STEPHANIE: Yeah, I don't know the answer to that either, but I would be really curious to know if that is already something that happens with something like Copilot. JOËL: Do better docs help machines, or are they for humans only? STEPHANIE: Whoa, that's a very [laughs] philosophical question, I think. It would make sense, though, that if we already have ways to parse and compile this kind of documentation, then I can see that incorporating them into the types of, like, generative problems that AI quote, unquote "solves" [chuckles] would be really interesting to find out. But anyone listening who kind of knows the answer to that or has experience working with AI tools and various types of code comment documentation would be really curious to know what your experience is like and if it improves your development workflow. So, for people who might be interested in getting better at documenting their code in the style of module docs, what would you say are some really great attributes of good documentation in this form? JOËL: I think, first of all, you have to write from the motivation of, like, if you were confused and wanting to better understand what a method does, what would you like to see? And I think coming from that perspective, and that was, in my case, I had been that person, and then I was like, okay, now that I've figured it out, I'm going to write it so that the next person is not confused. I have five or six things that I think were really valuable to add to the docs, a few of which we've already mentioned. But rapid fire, first of all, code example. I love code examples. I want a code example on every method. An explanation of expected usage. Here's what the method does. Here's how we expect you to use this method in any extra context about sort of intended use. Callouts for suggested alternatives. If there are methods that are similar, or there's maybe a sort of common mistake that you would reach for this method, put some sort of call out to say, "Hey, you probably came here trying to do X. If that's what you were actually trying to do, you should use method Y." Beyond that, a discussion of edge cases, so any sort of weird ways the method behaves. You know, when you pass nil to it, does it behave differently? If you call it in a different context, does it behave differently? I want to know that so that I'm not totally surprised. Links to external resources–really great if I want to, like, dig deeper. Is this method built on some sort of, like, algorithm that's documented elsewhere? Please link to that algorithm. Is this method integrating with some, like, third-party API? You know, they have some documentation that we could link to to go deeper into, like, what these search options do. Link to that. External links are great. I could probably find it by Googling myself, but you are going to make me very happy as a developer if you already give me the link. You'd mentioned capturing inputs and outputs. That's a great thing to scan for. Inputs and outputs, though, are more sometimes than just the arguments and return values. Although if we're talking about arguments, any sort of options hash, please document the keys that go in that because that's often not obvious from the code. And I've spent a lot of time source diving and jumping between methods trying to figure out like, what are the options I can pass to this hash? Beyond the explicit inputs and outputs, though, anything that is global state that you rely on. So, do you need to read something from an environment variable or even a global variable or something like that that might make this method behave differently in different situations? Please document that. Any situations where you might raise an error that I might not expect or that I might want to rescue from, let me know what are the potential errors that might get raised. And then, finally, any sorts of side effects. Does this method make a network call? Are you writing to the file system? I'd like to know that, and I'd have to, like, figure it out by trial and error. And sometimes, it will be obvious in just the description of the method, right? Oh, this method pulls data from a third-party API. That's pretty clear. But maybe it does some sort of, like, caching in the background or something to a file that's not really important. But maybe I'm trying to do a unit test that involves this, and now, all of a sudden, I have to do some weird stubbing. I'd like to know that upfront. So, those are kind of all the things I would love to have in my sort of ideal documentation comment that would make my life easier as a developer when trying to use some code. STEPHANIE: Wow. What a passionate plea [laughs]. I was very into listening to you list all of that. You got very animated. And it makes a lot of sense because I feel like these are kind of just the day-to-day developer issues we run into in our work and would be so awesome if, especially as the, you know, author where you have figured all of this stuff out, the author of a, you know, a method or a class, to just kind of tell us these things so we don't have to figure it out ourselves. I guess I also have to respond to that by saying, on one hand, I totally get, like, you want to be saved [chuckles] from those common pitfalls. But I think that part of our work is just going through that and playing around and exploring with the code in front of us, and we learn all of that along the way. And, ultimately, even if that is all provided to you, there is something about, like, going through it yourself that gives you a different perspective on it. And, I don't know, maybe it's just my bias against [laughs] all the inline text, but I've also seen a lot of that type of information captured at different levels of documentation. So, maybe it is a Confluence doc or in a wiki talking about, you know, common gotchas for this particular problem that they were trying to solve. And I think what's really cool is that, you know, everyone can kind of be served and that people have different needs that different styles of documentation can meet. So, for anyone diving deep in the source code, they can see all of those examples inline. But, for me, as a big Googler [laughs], I want to see just a nice, little web app to get me the information that I need to find. I'm happy having that a little bit more, like, extracted from my source code. JOËL: Right. You don't want to have to read the source code with all the comments in it. I think that's a fair criticism and, yeah, probably a downside of this. And I'm wondering, there might be some editor tooling that allows you to just collapse all comments and hide them if you wanted to focus on just the code. STEPHANIE: Yeah, someone, please build that for me. That's my passionate plea [laughs]. And on that note, shall we wrap up? JOËL: Let's wrap up. STEPHANIE: Show notes for this episode can be found at bikeshed.fm. JOËL: This show has been produced and edited by Mandy Moore. STEPHANIE: If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter. STEPHANIE: Or reach both of us at hosts@bikeshed.fm via email. JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week. ALL: Bye. AD: Did you know thoughtbot has a referral program? If you introduce us to someone looking for a design or development partner, we will compensate you if they decide to work with us. More info on our website at: tbot.io/referral. Or you can email us at referrals@thoughtbot.com with any questions.

Joël discusses the challenges he encountered while optimizing slow SQL queries in a non-Rails application. Stephanie shares her experience with canary deploys in a Rails upgrade. Together, Stephanie and Joël address a listener's question about replacing the wkhtml2pdf tool, which is no longer maintained. The episode's main topic revolves around the concept of multidimensional numbers and their applications in software development. Joël introduces the idea of treating objects containing multiple numbers as single entities, using the example of 2D points in space to illustrate how custom classes can define mathematical operations like addition and subtraction for complex data types. They explore how this approach can simplify operations on data structures, such as inventories of T-shirt sizes, by treating them as mathematical objects. EXPLAIN ANALYZE visualizer (https://explain.dalibo.com/) Canary in a coal mine (https://en.wikipedia.org/wiki/Sentinel_species#Canaries) Episode 413: Developer Tales of Package Management (https://bikeshed.thoughtbot.com/413) Docs for media-specific CSS (https://developer.mozilla.org/en-US/docs/Web/CSS/@media) Episode 386: Value Objects Revisited: The Tally Edition (https://bikeshed.thoughtbot.com/386) Money gem (https://github.com/RubyMoney/money) Transcript: STEPHANIE: Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Stephanie Minn. JOËL: And I'm Joël Quenneville. And together, we're here to share a bit of what we've learned along the way. STEPHANIE: So, Joël, what's new in your world? JOËL: I've recently been trying to do some performance enhancements to some very slow queries. This isn't a Rails app, so we're sort of combining together a bunch of different scopes. And the way they're composing together is turning out to be really slow. And I've reached for a tool that is just really fun. It's a visualizer for SQL query plans. You can put the SQL keywords in front of a query: 'EXPLAIN ANALYZE,' and it will then output a query plan, sort of how it's going to attempt to do the work. And that might be like, oh, we're going to use this index on this table to join on this other thing, and then we're going to...maybe this is a table that we think we're going to do a sequential scan through and, you know, it builds out a whole thing. It's a big block of text, and it's kind of intimidating to look at. So, there are a few websites out there that will do this. You just paste a query plan in, and they will build you a nice, little visualization, almost like a tree of, like, tasks to be done. Oftentimes, they'll also annotate it with metadata that they pulled from the query plan. So, oh, this particular node is the really expensive one because we're doing a sequential scan of this table that has 15 million rows in it. And so, it's really useful to then sort of pinpoint what are the areas that you could optimize. STEPHANIE: Nice. I have known that you could do that EXPLAIN ANALYZE on a SQL query, but I've never had to do it before. Is this your first time, or is it just your first time using the visualizer? JOËL: I've played around with EXPLAIN ANALYZE a little bit before. Pro tip: In Rails, if you've got a scope, you can just chain dot explain on the end, and instead of running the query, it will run the EXPLAIN version of it and return the query plan. So, you don't need to, like, turn into SQL then manually run it in your database system to get the EXPLAIN. You can just tack a dot explain on there to get the query plan. It's still kind of intimidating, especially if you've got a really complex query that's...this thing might be 50 lines long of EXPLAIN with all this indentation and other stuff. So, putting it into a sort of online visualizer was really helpful for the work that I was doing. So, it was my first time using an online visualizer. There are a few out there. I'll link to the one that I used in the show notes. But I would do that again, would recommend. STEPHANIE: Nice. JOËL: So, Stephanie, what's new in your world? STEPHANIE: So, I actually just stepped away from being in the middle of doing a Rails upgrade [chuckles] and releasing it to production just a few minutes before getting on to record with you on this podcast. And the reason I was able to do that, you know, without feeling like I had to just monitor to see how it was going is because I'm on a project where the client is using canary deploys. And I was so pleasantly surprised by how easy it made this experience where we had decided to send the canary release earlier this morning. And the way that they have it set up is that the canary goes to 10% of traffic. 10% of the users were on Rails 7 for their sessions. And we saw a couple of errors in our error monitoring service. And we are like, "Okay, like, let's take a look at this, see what's going on." And it turns out it was not too big of a deal because it had to do with, like, a specific page. And, for the most part, if a user did encounter this error, they probably wouldn't again after refreshing because they had, like, a 90% chance [chuckles] of being directed to the previous version where everything is working. And we were kind of making that trade-off of like, oh, we could hotfix this right now on the canary release. But then, as we were starting to debug a little bit, it was a bit hairier than we expected originally. And so, you know, I said, "I have to hop on to go record The Bike Shed. So, why don't we just take this canary down just for the time being to take that time pressure off? And it's Friday, so we're heading into the weekend. And maybe we can revisit the issue with some fresh eyes." So, I'm feeling really good, actually. And I'm glad that we were able to do something that seems scary, but there were guardrails in place to make it a lot more chill. JOËL: Yay for the ability to roll back. You used the term canary release. That's not one that I'm familiar with. Can you explain what a canary release is? STEPHANIE: Oh yeah. Have you heard of the phrase 'Canary in the coal mine'? JOËL: I have. STEPHANIE: Okay. So, I believe it's the same idea where you are, in this case, releasing a potentially risky change, but you don't want to immediately make it available to, like, all of your users. And so, you send this change to, like, a small reach, I suppose, and give it a little bit of a test and see [chuckles] what comes back. And that can help inform you of any issues or risks that might happen before kind of committing to deploying a potentially risky change with a bigger impact. JOËL: Is this handled with something like a feature flag framework? Or is this, like, at an infrastructure level where you're just like, "Hey, we've got the canary image in, like, one container on one server, and then we'll redirect 10% of traffic to that to be served by that one and the other 90% to be served by the old container or something like that"? STEPHANIE: Yeah, in this case, it was at the infrastructure level. And I have also seen something similar at a feature flag level, too, where you're able to have some more granularity around what percent of users are seeing a feature. But I think with something like a Rails upgrade, it was nice to be able to have that at that infrastructure level. It's not necessarily, like, a particular page or feature to show or not show. JOËL: Yeah, I think you would probably want that at a higher level when you're changing over the entire app. Is this something that you had to custom-build yourself or something that just sort of came out of the box with some of the infrastructure tools you're using? STEPHANIE: It came out of the box, actually. I just joined this client project this week and was very delighted to see just some really great deployment infrastructure and getting to meet the DevOps engineers, too, who built it. And they're really proud of it. They kind of walked us through our first release earlier this week. And he was telling me, the DevOps engineer, that this was actually his favorite part of the job, is walking people through their first release and being their buddy while they do it. Because I think he gets to also see users interact with the tool that he built, and he had a lot of pride in that, so it was a very delightful experience. JOËL: That's so wonderful. I've been on so many projects where the sort of infrastructure side of things is not the team's strong point, and releasing can be really scary. And it's great to hear the opposite of that. We recently received a question for Stephanie based on an earlier episode. So, the question asks, "In episode 413, Stephanie discussed a recent issue she encountered with wkhtml2pdf. The episode turned into a deeper discussion about package management, but I don't think it ever cycled back to the conclusion. I'm curious: how did Stephanie solve this dilemma? We're facing the same issue on a project that my team maintains. It's an old codebase, and there are bits of old code that use wkhtml2pdf to generate print views of our data in our application. The situation is fairly dire. wkhtml2pdf is no longer maintained. In fact, it won't even be available to install from our operating system's package repositories in June. We're on FreeBSD, but I assume the same will be eventually true for other operating systems. And so, unless you want to maintain some build step to check out and compile the source code for an application that will no longer receive security updates, just living with it isn't really an option. There are three options we're considering. One, eliminate the dependency entirely. Based on user feedback, it sounds like our old developers were using this library to generate PDFs when what users really wanted was an easy way to print. So, instead of downloading a PDF, just ensure the screen has a good print style sheet and register an onload handler to call window dot print. We're thinking we could implement this as an A/B test to the feature to test this theory. Or two, replace wkhtml2pdf with a call to Headless Chrome and use that to generate the PDF. Or, three, replace wkhtml2pdf with a language-level package. For us, that might be the dompdf library available via Composer because we're a PHP shop." Yeah, a lot to unpack here. Any high-level thoughts, Stephanie? STEPHANIE: My first thought while I was listening to you read that question is that wkhtml2pdf is such a mouthful [laughs]. And I was impressed how you managed to say it at least, like, five times. JOËL: So, I try to say that five times fast. STEPHANIE: And then, my second high-level thought was, I'm so sorry to Brian, our listener who wrote in, because I did not really solve this dilemma [chuckles] for my project and team. I kind of kicked the can down the road, and that's because this was during a support and maintenance rotation that I've talked a little bit about before on the show. I was only working on this project for about a week. And what we thought was a small bug to figure out why PDFs were a little bit broken turned out, as you mentioned, to be this kind of big, dire dilemma where I did not feel like I had enough information to make a good call about what to do. So, I kind of just shared my findings that, like, hey, there is kind of a risk and hoping that someone else [laughs] would be able to make a better determination. But I really was struck by the options that you were considering because it was actually a bit of a similar situation to the bug I was sharing where the PDF that was being generated that was slightly broken. I don't think it was, like, super valuable to our users that it be in the form of a PDF. It really was just a way for them to print something to have on handy as a reference from, you know, some data that was generated from the app. So, yeah, based on what you're sharing, I feel really excited about the first one. Joël, I'm sure you have some opinions about this as well. JOËL: I love sort of the bigger picture thinking that Brian is doing here, sort of stepping back and being like, wait, why do we even need PDF here, and how are our customers using it? I think those are the really good questions to ask before sinking a ton of time into coming up with something that might be, like, a bit of a technical wonder. Like, hey, we managed to, like, do this PDF generation thing that we had to, like, cobble together so many other things. And it's so cool technically, but does it actually solve the underlying problem? So, shout out to Brian for thinking about it in those terms. I love that. Second cool thing that I wanted to shout out, because I think this is a feature of browsers that not many people are aware of; you can have multiple style sheets for your page, and you can tag them to be for different media. So, you can have a style sheet that only gets applied when you print versus when you display on screen. And there are a couple of others. I don't remember exactly what they are. I'll link to the docs in the show notes. But taking advantage of this, like, this is old technology but making that available and saying, "Yeah, we'll make it so that it's nice when you print, and we'll maybe even, you know, a link or a button with JavaScript so that you could just Command-P or Control-P to print. But we'll have a button in there as well that will allow you to print to PDF," and that solves your problem right there. STEPHANIE: Yeah, that's really cool. I didn't know that about being able to tag style sheets for different media types. That's really fascinating. And I like that, yeah, we're just eliminating this dependency on something, like, potentially really complex with a, hopefully, kind of elegant and modern solution, maybe. JOËL: And your browser is already able to do so many of these things. Why do we sort of try to recreate it? Printing is a thing browsers have been able to do for a long time. Printing to PDF is a thing that you can do for a long time. I will sometimes use that on sites where I need to, let's say I'm purchasing something, and I need some sort of receipt to expense, but they won't give me a download, a PDF download that I can send to the accounting team, so I will print to PDF the, like, HTML view. And that works just fine. It's kind of a workaround hack. Sometimes, it doesn't work well because the HTML page is just not well set up to, like, show up on a PDF page. You get some, like, weird, like, pagination issues or things like that. But, you know, just a little bit of thought for a print style sheet, especially for something you know that people are likely going to want to print or to save to PDF, that's a nice touch. STEPHANIE: Yeah. So, good luck, Brian, and let us know how this goes and any outcomes you find successful. So, for today's longer topic, I was excited because I saw, Joël, you dropped something in our topic backlog: Multidimensional Numbers. I'm curious what prompted this idea and what you wanted to say about it. JOËL: We did an episode a while back where we talked about value objects, wrapping numbers, wrapping collections. This is Episode 386, and we were talking about tallying, specifically working with collections of T-shirt sizes and doing math on these sort of objects that might contain multiple numbers. And a sort of sidebar from that that we didn't really get into is the idea that objects that contain sort of multiple numbers can be treated as a number themselves. And I think a great example of this is something like a point in two-dimensional space. It's got an x coordinate, a y coordinate. It's two numbers, but you can treat sort of the combination of the two of them together as a single number. There's a whole set of coordinate math that you can do to do things like add coordinates together, subtract them, find the distance between them. There's a whole field of vector math that we can do on those. And I think learning to recognize that numbers are not just instances of the integer or the float class but that there could be these more complex things that are also numbers is maybe an important realization and something that, as developers, if we think of these sort of more complex values as numbers, or at least mathematical objects, then that will help us write better code. STEPHANIE: Cool. Yeah. When you were first talking about 2D points, I was thinking about if I have experience working with that before or, like, having to build something really heavily based off of, like, a canvas or, you know, a coordinate system. And I couldn't think of any really good examples until I thought about, like, geographic locations. JOËL: Oh yeah, like a latitude, longitude. STEPHANIE: Yeah, exactly. Like, that is a lot more common, I think, for various types of just, like, production applications than 2D points if you're not working on, like, a video game or something like that, I think. JOËL: Right, right. I think you're much more likely to be working with 2D points on some more sort of front-end-heavy application. I was talking with someone this week about managing a seat map for concerts and events like that and sort of creating a seat map and have it be really interactive, and you can, like, click on seats and things like that. And depending on the level of libraries you're using to build that, you may have to do a lot of 2D math to make it all come together. STEPHANIE: Yeah. So, I would love to get into, you know, maybe we've realized, okay, we have some kind of compound number. What are some good reasons for using them differently than you would a primitive? JOËL: So, you mentioned primitives, and I think this is where maybe I'm developing a reputation about, like, always wanting value objects for everything. But it would be really easy, let's say, for an xy point to be just an array of two numbers or maybe even a hash with an x key and a y key. What's tricky about that is that then you don't have the ability to do math on them. Arrays do define the plus operator, but they don't do what you want them to do with points. It's the set union. So, adding two points would not at all do what you want, or subtracting two points. So, instead, if you have a custom 2D point class and you can define plus and minus on there to do the right thing, now they're not pairs of numbers, two values; they're a single value, and you can treat them as if they are just a single number. STEPHANIE: You mentioned that arrays don't do the right thing when you try to add them up. What is the right thing that you're thinking of then? JOËL: It probably depends a little bit on the type of object you're working with. So, with 2D points, you're probably trying to do vector addition where you're effectively saying almost, like, "Shift this point in 2D space by the amount of this other point." Or if you're doing a subtraction, you might even be asking, like, "What is the distance between these two points?" Euclidean distance, I think, is the technical term for this. There's also a couple of different ways you can multiply values. You can multiply a 2D point by just a sort of, not by another point, but by just an integer. That's called scaling. So, you're just like, oh, take this point in 2D space, but make it bigger, make it five times bigger or five times further from the origin. Or you can do some stuff with other points. But what you don't want to do is turn this into, if you're starting with arrays, you don't want to turn this into an array of four points. When you add two points in 2D space, you're not trying to create a point in 4D space. STEPHANIE: Whoa, I mean [laughs], maybe you're not. JOËL: You could but -- [laughter] STEPHANIE: Yeah. While you were saying that, I guess that is what is really cool about wrapping, encapsulating them in objects is that you get to decide what that means for you and your application, and -- JOËL: Yeah. Well, plus can mean different things, right? STEPHANIE: Yeah. JOËL: On arrays, plus means combining two arrays together. On integers, it means you do integer math. And on points, it might be vector addition. STEPHANIE: Are there any other arithmetic operators you can think of that would be useful to implement if you were trying to create some functionality on a point? JOËL: That's a good question because I think realizing the inverse of that is also a really powerful thing. Just because you create a sort of new mathematical object, a point in 2D space, doesn't mean that necessarily every arithmetic operator makes sense on it. Does it make sense to divide a point by another point? Maybe not. And so, instead of going with the mindset of, oh, a point is a mathematical object, I now need to implement all of arithmetic on this, instead, think in terms of your domain. What are the operations that make sense? What are the operations you need for this point? And, you know, maybe the answer is look up what are the common sort of vector math operations and implement those on your 2D point. Some of them will map to arithmetic operators like plus and minus, and then some of them might just be some sort of custom method where maybe you say, "Oh, I want the Euclidean distance between these two points." That's just a thing. Maybe it's just a named instance method on there. But yeah, don't feel like you need to implement all of the math operators because that's a mistake that I have made and then have ended up, like, implementing nonsensical things. STEPHANIE: [laughs] Creating your own math. JOËL: Yes, creating my own math. I've done this even on where I've done value objects to wrap single values. I was doing a class to represent currency, and I was like, well, clearly, you need, like, methods to, like, add or subtract your currency, and that's another thing. If you have, let's say, a plus method, now you can plug it into, let's say, reduce plus. And you can just sum a list of these currency objects and get back a new currency. It's not even going to give you back an integer. You just get a sort of new currency object that is the sum of all the other ones, and that's really nice. STEPHANIE: Yeah, that's really cool. It reminds me of all the magic of enumerable that you had talked about in a previous conference talk, where, you know, you just get so much out of implementing those basic operators that, like, kind of scales in handiness. JOËL: Yes. Turns out Ruby is actually a pretty nice system. If you have objects that respond to some common methods and you plug them into enumerable, and it just all kind of works. STEPHANIE: So, one thing you had said earlier that I've felt kind of excited about and wanted to highlight was you mentioned all the different ways that you could represent a 2D point with more primitive data stores, so, you know, an array of two integers, a hash with xy keys. It got me thinking about how, yeah, like, maybe if your system has to talk to another system and you're importing data or exporting data, it might eventually need to take those forms. But what is cool about having an encapsulated object in your application is you can kind of control those boundaries a little bit and have more confidence in terms of the data types that you're using within your system by having various ways to construct that, like, domain object, even if the data coming in is in a different shape. JOËL: And I think that you're hitting on one of the real beauties of object-oriented programming, where the sort of users of your object don't need to know about the internal representation. Maybe you store an array internally. Maybe it's two separate instance variables. Maybe it's something else entirely. But all that the users of your, let's say, 2D point object really need to care about is, hey, the constructor wants values in this shape, and then I can call these domain methods on it, and then the rest just sort of happens. It's an implementation detail. It doesn't matter. And you alluded, I think, to the idea that you can sort of create multiple constructors. You called them constructors. I tend to call them that as well. But they're really just class methods that will kind of, like, add some sugar on top of the constructor. So, you might have, like, a from array pair or from hash or something like that that allows you to maybe do a little bit of massaging of the data before you pass it into your constructor that might want some underlying form. And I think that's a pattern that's really nice. STEPHANIE: Yeah, I agree. JOËL: Something that can be interesting there, too, is that mathematically, there are multiple ways you can think of a 2D point. An xy coordinate pair is a common one, but another sort of system for representing a point in 2D space is called the polar coordinate system. So, you have some sort of, like, origin point. You're 0,0. And then, instead of saying so many to the left and so many up from that origin point, you give an angle and a distance, and that's where your point is. So, an angle and distance point, I think, you know, theta and magnitude are the fancy terms for this. You could, instead of creating a separate, like, oh, I have a polar coordinate point and a Cartesian coordinate point, and those are separate things, you can say, no, I just have a point in 2D space. They can be constructed from either an xy coordinate pair or a magnitude angle pair. Internally, maybe you convert one to the other for internal representation because it makes the math easier or whatever. Your users never need to know that. They just pass in the values that they want, use the constructor that is most convenient for them, and it might be both. Maybe some parts of the app require polar coordinates; some require Cartesian coordinates. You could even construct one of each, and now you can do math with each other because they're just instances of the same class. STEPHANIE: Whoa. Yeah, I was trying to think about transforming between the two types as well. It's all possible [laughs]. JOËL: Yes. Because you could have reader-type methods on your object that say, oh, for this point, give me its x coordinate; give me its y coordinate. Give me its distance from the origin. Give me its angle from the origin. And those are all questions you can ask that object, and it can calculate them. And you don't need to care what its internal representation is to be able to get all four of those. So, we've been talking about a lot of these sort of composite numbers, not composite numbers, that's a separate mathematical thing, but numbers that are composed of sort of multiple sub-numbers. And what about situations where you have two things, and one of them is not a number? I'm thinking of all sorts of units of measure. So, I don't just have three. I have three, maybe...and we were talking about currency earlier, so maybe three U.S. dollars. Or I don't just have five; I have five, you know, let's say, meters of distance. Would you consider something like that to be one of these compound number things? STEPHANIE: Right. I think I was–when we were originally talking about this, conflating the two. But I realized that, you know, just because we're adding context to a number and potentially packaging it as a value object, it's still different from what we're talking about today where, you know, there's multiple components to the number that are integral or required for it to mean what we intended to mean, if that makes sense. JOËL: Yeah. STEPHANIE: So yeah, I guess we did want to kind of make a distinction between value objects that while the additional context is important and you can implement a lot of different functionality based on what it represents, at the end of the day, it only kind of has one magnitude or, like, one integer to kind of encapsulate it represented as a number. Does that sound right? JOËL: Yeah. You did throw out the words encapsulation and value object. So, in a situation maybe where I have three US dollars, would you create some kind of custom object to wrap that? Or is that a situation where you'd be more comfortable using some kind of primitive? Like, I don't know, maybe an array pair of three and the symbol USD or something like that. STEPHANIE: Oh, I would definitely not do that [laughter]. Yeah. Like I, you know, for the most part, I think I've seen that as a currency object, and that expands the world of what we can do with it, converting into a lot of different other currencies. And yeah, just making sure those things don't get divorced from each other because that context is what gives it meaning. But when it comes to our compound numbers, it's like, without all of the components, it doesn't make sense, or it doesn't even represent the same, like, numerical value that we were trying to convey. JOËL: Right. You need both, or, you know, it could be more than two. It could be three, four, or five numbers together to mean something. You mentioned conversions, which I think is something that's also interesting because a lot of units of measure have sort of multiple ways of measuring, and you often want to convert between them. And maybe that's another case where encapsulation is really nice where, you know, maybe you have a distance object. And you have five meters, and you put that into your distance object, but then somebody wants it in feet somewhere else or in centimeters, or something like that. And it can just do all the conversion math safely inside that object, and the user doesn't have to worry about it. STEPHANIE: Right. This is maybe a bit of a tangent, but as a Canadian living in the U.S., I don't know [laughs] if you have any opinions about converting meters and feet. JOËL: The one I actually do the most often is converting Celsius to Fahrenheit and vice versa. You know, I've been here, what, 11 years now? I don't have a great intuition for Fahrenheit temperatures. So, I'm converting in my head just [laughs] on a daily basis. STEPHANIE: Yeah, that makes sense. Conversions: they're important. They help out our friends who [laughs] are on different systems of measurement. JOËL: There's a classic story that I love about unit conversions. I think it's one of the NASA Mars missions. STEPHANIE: Oh yeah. JOËL: You've heard of this one. It was trying to land on Mars, and it burned up in the atmosphere because two different teams had been building different components and used different unit systems, both according to spec for their own module. But then, when the modules try to talk to each other, they're sending over numbers in meters instead of feet or something like that. And it just caused [laughs] this, like, multi-year, multi-billion dollar project to just burn up. STEPHANIE: That's right. So, lesson of the day is don't do that. I can think of another example where there might be a little bit of misconceptions in terms of how to represent it. And I'm thinking about time and when that has been represented in multiple parts, such as in hours and, minutes and seconds. Do you have any initial impressions about a piece of data like that? JOËL: So, that's really interesting, right? Because, at first glance, it looks like, oh, it's, like, a triplet of hour, minute, seconds. It's sort of another one of these sort of compound numbers, and I guess you could implement it that way. But in reality, you're tracking a single quantity, the amount of time elapsed, and that can be represented with a single number. So, if you're representing, let's say, time of day, what would show up on your clock? That could be, depending on the resolution, number of, let's say, seconds since midnight, and that's a single counter. And then, you can do some math on it to get hours, minutes, seconds for a particular moment. But really, it's a single quantity, and we can do that with time. We can't do that with a 2D point. Like, it has to have two components. STEPHANIE: So, do you have a recommendation for what unit of time time would best be stored? I'm just thinking of all the times that I've had to do that millisecond, you know, that conversion of, you know, however many thousands of milliseconds in my head into something that actually means [laughs] something to me as a human being who measures time in hours and minutes. JOËL: My recommendation is absolutely go for a single number that you store in your, let's say, time of day object. It makes the math so much easier. You don't have to worry about, like, overflowing from one number into another when you're doing math or anything like that. And then the number that you count should be at the whatever the smallest resolution you care at. So, is there ever any time where you want to distinguish between two different milliseconds in time? Or maybe you're like, you know what? These are, like, we're tracking time of day for appointments. We don't care about the difference between two milliseconds. We don't need to track them independently. We don't even care about seconds. The most granular we ever care about things is by the minute. And so, maybe then your internal number that you track is a counter of minutes since midnight. But if you need more precision, you can go down to seconds or milliseconds or nanoseconds. But yeah, find what is the sort of the least resolution you want to get away with and then make that the unit of measure for a single counter in your object. And then encapsulate that so that nobody else needs to care that, internally, your time of day object is doing milliseconds because nobody wants to do that math. Just give me a nice, like, hours and minutes method on your object, and I will use that. I don't need to know internally what it's using. Please don't just pass around integers; wrap it in an object, especially because integers, there's enough times where you're doing seconds versus milliseconds. And when I just have an integer, I never know if the person storing this integer means seconds or milliseconds. So, I'm just like, oh, I'm going to pass to this, like, user object, a, like, time integer. And unless there's a comment or a constant, you know, that's named something duration in milliseconds or something like that, you know, or sometimes even, like, one year in milliseconds, or there's no way of knowing. STEPHANIE: Yeah. That makes a lot of sense. When you kind of choose a standard of a standard unit, it's, like, possible to make it easier [laughs]. JOËL: So, circling back to sort of the initial thing that sparked this conversation, the previous episode about T-shirt inventories, there we were dealing with what started off as, like, a hash of different T-shirt sizes and quantities of T-shirts that we had in that size, so small (five), medium (three), large (four). And then, we eventually turned that into a value object that represented...I think we called it a tally, but maybe we called it inventory. And this may be wrong, so tell me if I'm wrong here, I think we can kind of treat that as a number, as, like, one of these compound numbers. It's a sort of multidimensional number where you say, well, we have sort of three dimensions where we can have numbers that sort of increase and decrease independently. We can do math on these because we can take inventories or tallies and add and subtract them. And that's what we ended up having to do. We created a value object. We implemented plus and minus on it. There are rules for how the math works. I think this is a multidimensional number with the definition we're working on this show. Am I wrong here? STEPHANIE: I wouldn't say that you're wrong. I think I would have to think a little [laughs] more to say definitively that you're right. But I know that this example came from, you know, an application I was actually working on. And one of the main things that we had to do with these representations [laughs], I'm hesitant to call them a number, especially, but we had to compare these representations frequently because an inventory, for example, in a warehouse, wanting to make sure that it is equal to or there's enough of the inventory if someone was placing an order, which would also contain, like, a representation of T-shirt size inventory. And that was kind of where some of that math happened because, you know, maybe we don't want to let someone place an order if the inventory at the warehouse is smaller than their order, right? So, there is something really compelling about the comparison operations that we were doing that kind of is leaning me in the direction of, like, yeah, like, it makes sense to me to use this in a way that I would compare, like, quantities or numbers of something. JOËL: I think one thing that was really compelling to me, and that kind of blew my mind, was that we were trying to, like, figure out some things like, oh, we've got so many people with these size preferences, and we've got so many T-shirts across different warehouses. And we're summing them up and we're trying to say like, "How many do we need to purchase if there is a deficit?" And we can come up with effectively a formula for this. We're like, sum these numbers, when we're talking about just before we introduce sizes when it's just like, oh, people have T-shirts. They all get the count of people and a count of T-shirts in our warehouse, and we find, you know, the difference between that. And there's a few extra math operations we do. Then you introduce size, and you break it down by, oh, we've got so many of each. And now the whole thing gets really kind of messy and complicated. And you're doing these reduces and everything. When we start treating the tally of T-shirts as an object, and now it's a number that responds to plus and minus, all of a sudden, you can just plug those back into the original formula, and it all just works. The original formula doesn't care whether the numbers you're doing this formula on are simple integers or these sort of multidimensional numbers. And that blew my mind, and it was so cool. STEPHANIE: Yeah, that is really neat. And you get a lot of added benefits, too. I think the other important piece in the T-shirt size example was kind of tracking the state change, and that's so much easier when you have an object. There's just a lot more you can do with it. And even if, you know, you're not persisting every single version of the representation, you know, because sometimes you don't want to, sometimes you're really just kind of only holding it in memory to figure out if you need to, you know, do something else. But other times, you do want to persist it. And it just plugs in really well with, like, the rest of object-oriented programming [laughs] in terms of interacting with the rest of your business needs, I think, in your app. JOËL: Yeah, turns out objects, they're kind of nice. And you can do math with them. Who knew? Math is not just about integers. STEPHANIE: And on that note, shall we wrap up? JOËL: Let's wrap up. STEPHANIE: Show notes for this episode can be found at bikeshed.fm. JOËL: This show has been produced and edited by Mandy Moore. STEPHANIE: If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter. STEPHANIE: Or reach both of us at hosts@bikeshed.fm via email. JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week. ALL: Byeeeeeee!!!!!! AD: Did you know thoughtbot has a referral program? If you introduce us to someone looking for a design or development partner, we will compensate you if they decide to work with us. More info on our website at: tbot.io/referral. Or you can email us at referrals@thoughtbot.com with any questions.

Stephanie has a delightful and cute Ruby thing to share: Honeybadger, the error monitoring service, has created exceptionalcreatures.com, where they've illustrated and characterized various common Ruby errors into little monsters, and they're adorable. Meanwhile, Joël encourages folks to submit proposals for RailsConf. Together, Stephanie and Joël delve into the nuances of adapting to and working within new codebases, akin to aligning with a shared mental model or vision. They ponder several vital questions that every developer faces when encountering a new project: the balance between exploring a codebase to understand its structure and diving straight into tasks, the decision-making process behind adopting new patterns versus adhering to established ones, and the strategies teams can employ to assist developers who are familiarizing themselves with a new environment. Honeybadger's Exceptional Creatures (https://www.exceptionalcreatures.com/) RailsConf CFP coaching sessions (https://docs.google.com/forms/d/e/1FAIpQLScZxDFaHZg8ncQaOiq5tjX0IXvYmQrTfjzpKaM_Bnj5HHaNdw/viewform) HTTP Cats (https://http.cat/) Support and Maintenance Episode (https://bikeshed.thoughtbot.com/409) Transcript:  JOËL: Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Joël Quenneville. STEPHANIE: And I'm Stephanie Minn. And together, we're here to share a bit of what we've learned along the way. JOËL: So, Stephanie, what's new in your world? STEPHANIE: I have a delightful and cute Ruby thing to share I'd seen just in our internal company Slack. Honeybadger, the error monitoring service, has created a cute little webpage called exceptionalcreatures.com, where they've basically illustrated and characterized various common Ruby errors into little monsters [laughs], and I find them adorable. I think their goal is also to make it a really helpful resource for people encountering these kinds of errors, learning about them for the first time, and figuring how to triage or debug them. And I just think it's a really cool way of, like, making it super approachable, debugging and, you know, when you first encounter a scary error message, can be really overwhelming, and then Googling about it can also be equally [chuckles] overwhelming. So, I just really liked the whimsy that they kind of injected into something that could be really hard to learn about. Like, there are so many different error messages in Ruby and in Rails and whatever other libraries you're using. And so, that's kind of a...I think they've created a one-stop shop for, you know, figuring out how to move forward with common errors. And I also like that it's a bit of a collective effort. They're calling it, like, a bestiary for all the little creatures [laughs] that they've discovered. And I think you can, like, submit your own favorite Ruby error and any guidance you might have for someone trying to debug it. JOËL: That's adorable. It reminds me a little bit of HTTP status codes as cat memes site. It has that same energy. One thing that I think is really interesting is that because it's Honeybadger, they have stats on, like, frequency of these errors, and a lot of these ones are tied to...I think they're picking some of the most commonly surfaced errors. STEPHANIE: Yeah, there's little, like, ratings, too, for how frequently they occur, kind of just like, I don't know, Pokémon [laughs] [inaudible 02:31]. I think it's really neat that they're using something like a learning from their business or maybe even some, like, proprietary information and sharing it with the world so that we can learn from it. JOËL: I think one thing that's worth specifying as well is that these are specific exception classes that get raised. So, they're not just, like, random error strings that you see in the wild. They don't often have a whole lot of documentation around them, so it's nice to see a dedicated page for each and a little bit of maybe how this is used in the real world versus maybe how they were designed to be used. Maybe there's a line or two in the docs about, you know, core Ruby when a NoMethodError should be raised. How does NoMethodError actually get used, you know, in real life, and the exceptions that Honeybadger is capturing. That's really interesting to see. STEPHANIE: Yeah, I like how each page for the exception class, and I'm glad you made that distinction, is kind of, like, crowdsourced guidance and information from the community, so I think you could even, you know, contribute to it if you wanted. But yeah, just a fun, little website to bring you some delight when you're on your next head-smacking, debugging adventure [laughs]. JOËL: And I love that it brings some joy to the topic, but, honestly, I think it's a pretty good reference. I could see myself linking to this anytime I want to have a deeper discussion on exceptions. So, maybe there's a code review, and maybe I want to suggest that we raise a different error than the one that we're doing. I could see myself in that GitHub comment being like, "Oh, instead of, you know, raising an exception here, why don't we instead raise a NoMethodError or something like that?" And then link to the bestiary page. STEPHANIE: So, Joël, what's new in your world? JOËL: So, just recently, RailsConf announced their call for proposals. It's a fairly short period this year, only about three-ish weeks long. So, I've been really encouraging colleagues to submit and trying to be a resource for people who are interested in speaking at conferences. We did a Q&A session with a fellow thoughtboter, Aji Slater, who's also a former RailsConf speaker, about what makes for a good talk, what is it like to submit to a call for proposals, you know, kind of everything from the process from having an idea all the way to stage presence and delivering. And there's a lot of great questions that got asked and some good discussion that happened there. STEPHANIE: Nice. Yeah, I think I have noticed that you are doing a lot more to help, especially first-time speakers give their first conference talk this year. And I'm wondering if there's anything you've learned or any hopes and dreams you have for kind of the amount of time you're investing into supporting others. JOËL: What I'd like to see is a lot of people submitting proposals; that's always a great thing. And, a proposal, even if it doesn't get accepted, is a thing that you can resubmit. And so, having gone through the effort of building a proposal and especially getting it maybe peer-reviewed by some colleagues to polish your idea, I think is already just a really great exercise, and it's one that you can shop around. It's one that you can maybe convert into a blog post if you need to. You can convert that into some kind of podcast appearance. So, I think it's a great way to take an idea you're excited about and focus it, even if you can't get into RailsConf. STEPHANIE: I really like that metric for success. It reminds me of a writer friend I have who actually was a guest on the show, Nicole Zhu. She submits a lot of short stories to magazines and applications to writing fellowships, and she celebrates every rejection. I think at the end of the year, she, like, celebrates herself for having received, you know, like, 15 rejections or something that year because that meant that she just went for it and, you know, did the hard part of doing the work, putting yourself out there. And that is just as important, you know, if not more than whatever achievement or goal or the idea of having something accepted. JOËL: Yeah, I have to admit; rejection hurts. It's not a fun thing to go through. But I think even if you sort of make it to that final stage of having written a proposal and it gets rejected, you get a lot of value out of that journey sort of regardless of whether you get accepted or not. So, I encourage more people to do that. To any of our listeners who are interested, the RailsConf call for proposals goes through February 13th, 2024. So, if you are listening before then and are inspired, I recommend submitting. If you're unsure of what makes for a good CFP, RailsConf is currently offering coaching sessions to help craft better proposals. They have one on February 5th, one on February 6th, and one on February 7th, so those are also options to look into if this is maybe your first time and you're not sure. There's a signup form. We'll link to it in the show notes. STEPHANIE: So, another update I have that I'm excited to get into for the rest of the episode is my recent work on our support and maintenance team, which I've talked about on the show before. But for any listeners who don't know, it's a kind of sub-team at thoughtbot that is focused on helping maintain multiple client projects at a time. But, at this point, you know, there's not as much active feature development, but the work is focused on keeping the codebase up to date, making any dependency upgrades, fixing any bugs that come up, and general support. So, clients have a team to kind of address those things as they come up. And when I had last talked about it on the podcast, I was really excited because it was a bit of a different way of working. I felt like it was very novel to be, you know, have a lot of different projects and domains to be getting into. And knowing that I was working on this team, like, short-term and, you know, it may not be me in the future continuing what I might have started during my rotation, I thought it was really interesting to be optimizing towards, like, completion of a task. And that had kind of changed my workflow a bit and my process. JOËL: So, now that you've been doing work on the support and maintenance team for a while and you've kind of maybe gotten more comfortable with it, how are you generally feeling about this idea of sort of jumping into new codebases all the time? STEPHANIE: It is both fun and more challenging than I thought it would be. I tend to actually really enjoy that period of joining a new team or a project and exploring, you know, a codebase and getting up to speed, and that's something that we do a lot as consultants. But I think I started to realize that it's a bit of a tricky balance to figure out how much time should I be spending understanding what this codebase is doing? Like, how much of the application do I need to be understanding, and how much poking around should I be doing before just trying to get started on my first task, the first starter ticket that I'm given? There's a bit of a balance there because, on one hand, you could just immediately start on the task and kind of just, you know, have your blinders [chuckles] on and not really care too much about what the rest of the code is doing outside of the change that you're trying to make. But that also means that you don't have that context of why certain things are the way they are. Maybe, like, the way that you want to be building something actually won't work because of some unexpected complexity with the app. So, I think there, you know, needs to be time spent digging around a little bit, but then you could also be digging around for a long time [chuckles] before you feel like, okay, I finally have enough understanding of this new codebase to, like, build a feature exactly how a seasoned developer on the team might. JOËL: I imagine that probably varies a little bit based on the task that you're doing. So, something like, oh, we want to upgrade this codebase to Ruby 3.3, probably requires you to have a very different understanding of the codebase than there's a bug where submitting a comment double posts it, and you have to dig into that. Both of those require you to understand the application on very different levels and kind of understand different mental models of what the app is doing. STEPHANIE: Yeah, absolutely. That's a really good point that it can depend on what you are first asked to work on. And, in fact, I actually think that is a good guidepost for where you should be looking because you could develop a mental model that is just completely unrelated [chuckles] to what you're asked to do. And so, I suppose that is, you know, usually a good place to start, at least is like, okay, I have this first task, and there's some understanding and acceptance that, like, the more you work on this codebase, the more you'll explore and discover other parts of it, and that can be on a need to know kind of basis. JOËL: So, I'm thinking that if you are doing something like a Ruby upgrade or even a Rails upgrade, a lot of what you care about the app is going to be on a more mechanical level. So, you want to know what gems you're using. You want to know what different patterns are being used, maybe how callbacks are happening, any particular features that are version-specific that are being used, things like that. Whereas if you're, you know, say, fixing a bug, you might care a lot more about some of the product-level concerns. What are we actually trying to do here? What is the expected user experience? How does this deviate from that? What were the underlying mental models of the developers? So, there's almost, like, two lenses you can look at the code. Now, I almost want to make this a two-dimensional thing, where you can look at it either from, like, a very kind of mechanical lens or a product lens in one axis. And then, on the other axis, you could look at it from a very high-level 10,000-foot view and maybe zoom in a little bit where you need, versus a very localized view; here's where the bug is happening on this page, and then sort of zoom out as necessary. And I could see different sorts of tasks falling in different quadrants there of, do I need a more mechanical view? Do I need a more product-focused view? And do I need to be looking locally versus globally? STEPHANIE: Wow. I can't believe you just created a Cartesian graph [laughs] for this problem on the fly. But I love it because I do think that actually lines up with different strategies I've taken before. It's like, how much do you even look at the code before deciding that you can't really get a good picture of it, of what the product is, without just poking around from the app itself? I actually think that I tend to start from the code. Like, maybe I'll see a screenshot that someone has shared of the app, you know, like a bug or something that they want me to fix, and then looking for that text in the code first, and then trying to kind of follow that path, whereas it's also, you know, perfectly viable to try to see the app being used in production, or staging, or something first to get a better understanding of some of the business problems it's trying to solve. JOËL: When you jump into a new codebase, do you sort of consciously take the time to plan your approach or sort of think about, like, how much knowledge of this new codebase do I need before I can, like, actually look at the problem at hand? STEPHANIE: Ooh, that's kind of a hard question to answer because I think my experience has told me enough times that it's never what I think it's going to [laughs] be, not never, but it frequently surprises me. It has surprised me enough times that it's kind of hard to know off the bat because it's not...as much as we work in frameworks that have opinions and conventions, a lot of the work that happens is understanding how this particular codebase and team does things and then having to maybe shift or adjust from there. So, I think I don't do a lot of planning. I don't really have an idea about how much time it'll take me because I can't really know until I dive in a little bit. So, that is usually my first instinct, even if someone is wanting to, like, talk to me about an approach or be, like, "Hey, like, how long do you think this might take based on your experience as a consultant?" This is my first task. Oftentimes, I really can't say until I've had a little bit of downtime to, in some ways, like, acquire the knowledge [chuckles] to figure that out or answer that question. JOËL: How much knowledge do you like to get upfront about an app before you dive into actually doing the task at hand? Are there any things, like, when you get access to a new codebase, that you'll always want to look at to get a sense of the project before you look at any tickets? STEPHANIE: I actually start at the model level. Usually, I am curious about what kinds of objects we're working with. In fact, I think that is really helpful for me. They're like building blocks, in order for me to, like, conceptually understand this world that's being represented by a codebase. And I kind of either go outwards or inwards from there. Usually, if there's a model that is, like, calling to me as like, oh, I'll probably need to interact with, then I'll go and seek out, like, where that model is created, maybe through controllers, maybe through background jobs, or something like that, and start to piece together entry points into the application. I find that helpful because a lot of the times, it can be hard to know whether certain pages or routes are even used at all anymore. They could just be dead code and could be a bit misleading. I've certainly been misled [chuckles] more than once. And so, I think if I'm able to pull out the main domain objects that I notice in a ticket or just hear people talk about on the team, that's usually where I gravitate towards first. What about you? Do you have a place you like to start when it comes to exploring a new codebase like that? JOËL: The routes file is always a good sort of overview of, like, what is going on in the app. Scanning the models directory is also a great start in a Rails app to get a sense of what is this app about? What are the core nouns in our vocabulary? Another thing that's good to look for in a codebase is what are the big types of patterns that they tend to use? The Rails ecosystem goes through fads, and, over time, different patterns will be more popular than others. And so, it's often useful to see, oh, is this an app where everything happens in service objects, or is this an app that likes to rely on view components to render their views? Things like that. Once you get a sense of that, you get a little bit of a better sense of how things are architected beyond just the basic MVC. STEPHANIE: I like that you mentioned fads because I think I can definitely tell, you know, how modern an app is or kind of where it might be stuck in time [chuckles] a little bit based on those patterns and libraries that it's heavily utilizing, which I actually find to be an interesting and kind of challenging position to be in because how do you approach making changes to a codebase that is using a lot of patterns or styles from back in the day? Would you continue following those same patterns, or do you feel motivated to introduce something new or kind of what might be trendy now? JOËL: This is the boring answer, but it's almost never worth it to, like, rewrite the codebase just to use a new pattern. Just introducing the new pattern in some of the new things means there are now two patterns. That's also not a great outcome for the team. So, without some other compelling reason, I default to using the established patterns. STEPHANIE: Even if it's something you don't like? JOËL: Yes. I'm not a huge fan of service objects, but I work in plenty of codebases that have them, and so where it makes sense, I will use service objects there. Service objects are not mutually exclusive with other things, and so sometimes it might make sense to say, look, I don't feel like I can justify a service object here. I'll do this logic in a view, or maybe I'll pull this out into some other object that's not a service object and that can live alongside nicely. But I'm not necessarily introducing a new pattern. I'm just deciding that this particular extraction might not necessarily need a service object. STEPHANIE: That's an interesting way to describe it, not as a pattern, but as kind of, like, choosing not to use the existing [chuckles] pattern. But that doesn't mean, like, totally shifting the architecture or even how you're asking other people to understand the codebase. And I think I'm in agreement. I'm actually a bit of a follower, too, [laughs], where I want to, I don't know, just make things match a little bit with what's already been created, follow that style. That becomes pretty important to me when integrating with a team in a codebase. But I actually think that, you know, when you are calibrating to a codebase, you're in a position where you don't have all that baggage and history about how things need to be. And maybe you might be empowered to have a little bit more freedom to question existing patterns or bring some new ideas to the team to, hopefully, like, help the code evolve. I think that's something that I struggle with sometimes is feeling compelled to follow what came before me and also wanting to introduce some new things just to see what the team might think about them. JOËL: A lot of that can vary depending on what is the pattern you want to introduce and sort of what your role is going to be on that team. But that is something that's nice about someone new coming onto a project. They haven't just sort of accepted that things are the way they are, especially for things that the team already doesn't like but doesn't feel like they have the energy to do anything better about it. So, maybe you're in a codebase where there's a ton of Ruby code in your ERB templates, and it's not really a pattern that you're following. It's just a thing that's there. It's been sort of the path of least resistance for a long time, and it's easier to add more lines in there, but nobody likes it. New person joins the team, and their naive exuberance is just like, "We can fix it. We can make it better." And maybe that's, you know, going back and rewriting all of your views. That's probably not the best use of their time. But it could be maybe the first time they have to touch one of these views, cleaning up that one and starting a conversation among the team. "Hey, here are some patterns that we might like to clean up some of these views instead," or "Here are maybe some guidelines for anything new that we write that we want to do to keep our views clean," and sort of start moving the needle in a positive direction. STEPHANIE: I like the idea of moving the needle. Even though I tend to not want to stir the pot with any big changes, one thing that I do find myself doing is in a couple of places in the specs, just trying to refactor a bit away from using lets. There were some kind of forward-thinking decisions made before when RSpec was basically going to deprecate using the describe block without prepending it with their module, so just kind of throwing that in there whenever I would touch a spec and asking other people to do the same. And then, recently, one kind of, like, small syntax thing that I hadn't seen before, and maybe this is just because of the age of the codebases in which I'm working, the argument forwarding syntax in Ruby that has been new, I mean, it's like not totally new anymore [laughs], but throwing that in there a little every now and then to just kind of shift away from this, you know, dated version of the code kind of towards things that other people are seeing and in newer projects. JOËL: I love harnessing that energy of being new on a project and wanting to make things better. How do you avoid just being, you know, that developer, though, that's new, comes in, and just wants to change everything for the sake of change or for your own personal opinions and just kind of moves things around, stirs the pot, but doesn't really contribute anything net positive to the team? Because I've definitely seen that as well, and that's not a good first contribution or, you know, contribution in general as a newer team member. How do we avoid being that person while still capitalizing on that energy of being someone new and wanting to make a positive impact? STEPHANIE: Yeah, that's a great point, and I kind of alluded to this earlier when I asked, like, oh, like, even if you don't like an existing syntax or pattern you'll still follow it? And I think liking something a different way is not a good enough reason [chuckles]. But if you are able to have a good reason, like I mentioned with the RSpec prepending, you know, it didn't need to happen now, but if we would hope to upgrade that gem eventually, then yeah, that was a good reason to make that change as opposed to just purely aesthetic [laughs]. JOËL: That's one where there is pretty much a single right answer to. If you plan to keep staying up to date with versions of RSpec, you will eventually need to do all these code changes because, you know, they're deprecating the old way. Getting ahead of that gradually as we touch spec files, there's kind of no downside to it. STEPHANIE: That's true, though maybe there is a person who exists out there who's like, "I love this old version of RSpec, and I will die on this hill that we have to stay on [laughs] it." But I also think that I have preferences, but I'm not so attached to them. Ideally, you know, what I would love to receive is just, like, curiosity about like, "Oh, like, why did you make this change?" And just kind of share my reasoning. And sometimes in that process, I realize, you know, I don't have a great reason, and I'll just say, "I don't have a great reason. This is just the way I like it. But if it doesn't work for you, like, tell me, and I'll consider changing it back. [chuckles]" JOËL: Maybe that's where there's a lot of benefit is the sort of curiosity on the part of the existing team and sort of openness to both learn about existing practices but also share about different practices from the new teammate. And maybe that's you're coming in, and you have a different style where you like to write tests, maybe without using RSpec's let syntax; the team is using it. Maybe you can have a conversation with the team. It's almost certainly not worth it for you to go and rewrite the entire test suite to not use let and be like, "Hey, first PR. I made your test better." STEPHANIE: Hundreds of files changed, thousands [laughs] of lines of code. I think that's actually a good segue into the question of how can a team support a new hire or a new developer who is still calibrating to a codebase? I think I'm curious about this being different from onboarding because, you know, there are a lot of things that we already kind of expect to give some extra time and leeway for someone who's new coming in. But what might be some ways to support a new developer that are less well known? JOËL: One that I really like is getting them involved as early as possible in code review because then they get to see the patterns that are coming in, and they can be involved in conversations on those. The first PR you're reviewing, and you see a bunch of tests leaning heavily on let, and maybe you ask a question, "Is this a pattern that we're following in this codebase? Did we have a particular motivation for why we chose this?" And, you know, and you don't want to do it in a sort of, like, passive-aggressive way because you're trying to push something else. It has to come from a place of genuine curiosity, but you're allowing the new teammate to both see a lot of the existing patterns kind of in very quick succession because you see a pretty good cross-section of those when you review code. And also, to have conversations about them, to ask anything like, "Oh, that's unusual. I didn't know we were doing that." Or, "Hey, is this a pattern that we're doing kind of just local to this subsystem, or is this something that's happening all the way? Is this a pattern that we're using and liking? Is this a thing that we were doing five years ago that we're phasing out, but there's still a few of them left?" Those are all, I think, great questions to ask when you're getting started. STEPHANIE: That makes a lot of sense. It's different from saying, "This is how we do things here," and expecting them to adapt or, you know, change to fit into that style or culture, and being open to letting it evolve based on the new team, the new people on the team and what they might be bringing to the table. I like to ask the question, "What do you need to know?" Or "What do you need to be successful?" as opposed to telling them what I think they need [laughs]. I think that is something that I actually kind of recently, not regret exactly, but I was kind of helping out some folks who were going to be joining the team and just trying to, like, shove all this information down their throats and be like, "Oh, and watch out for these gotchas. And this app uses a lot of callbacks, and they're really complex." And I think I was maybe coloring their [chuckles] experience a little bit and expecting them to be able to drink from the fire hose, as opposed to trusting that they can see for themselves, you know, like, what is going on, and form opinions about it, and ask questions that will support them in whatever they are looking to do. When we talked earlier about the four different quadrants, like, the kind of information they need to know will differ based off of their task, based off of their experience. So, that's one way that I am thinking about to, like, make space for a new developer to help shape that culture, rather than insisting that things are the way they are. JOËL: It can be a fine balance where you want to be open to change while also you have to remain kind of ruthlessly pragmatic about the fact that change can be expensive. And so, a lot of changes you need to be justified, and you don't want to just be rewriting your patterns for every new employee or, you know, just to follow the latest trends because we've seen a lot of trends come and go in the Rails ecosystem, and getting on all of them is just not worth our time. STEPHANIE: And that's the hard truth of there's always trade-offs [laughs] in software development, isn't that right? JOËL: It sure is. You can't always chase the newest shiny, as fun as that is. STEPHANIE: On that note, shall we wrap up? JOËL: Let's wrap up. STEPHANIE: Show notes for this episode can be found at bikeshed.fm. JOËL: This show has been produced and edited by Mandy Moore. STEPHANIE: If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter. STEPHANIE: Or reach both of us at hosts@bikeshed.fm via email. JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week. ALL: Byeeeeeeee!!!!!!! AD: Did you know thoughtbot has a referral program? If you introduce us to someone looking for a design or development partner, we will compensate you if they decide to work with us. More info on our website at: tbot.io/referral. Or you can email us at referrals@thoughtbot.com with any questions.

Joël shares his recent experience with Turbo, a JavaScript framework that simplifies adding interactivity to websites without extensive JavaScript coding. Stephanie gives an update on her quest to work from her office more, and the birds have arrived—most notably, chickadees. Stephanie and Joël address a listener question from Edward about the concept of a "spike" in software development. They discuss the nature of spikes, emphasizing that they are typically throwaway work aimed at learning and de-risking rather than producing final code, and explore how spikes can lead to better decision-making and prioritization in software development, especially in complex codebases. Transcript: STEPHANIE:  Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Stephanie Minn. JOËL: And I'm Joël Quenneville. And together, we're here to share a bit of what we've learned along the way. STEPHANIE: So, Joël, what's new in your world? JOËL: I'm pretty excited because this week, I actually got to use a little bit of Turbo for the first time. Turbo is Rails'...I guess it's not technically just for Rails. It's a sort of unobtrusive JavaScript framework that allows you to build a lot of interactive functionality without actually having to write a lot of JavaScript yourself, just by writing some HTML in a certain way. And you can add a lot of functionality and interactivity to your site without having to drop to custom writing some JavaScript. STEPHANIE: Cool. Yeah, that is exciting. I personally have not gotten to use too much of it in a production/client setting; only played around with it a little bit on my own to keep up with what's new and just kind of reading about how other people are excited to use it. So, what are your first impressions so far? JOËL: It's pretty nice. It, you know, works as advertised. My situation, I was rendering a calendar view of a lot of events, and this is completely server-rendered. And I realized, wait a minute, there are some days where I've got, like, 20 events, and I really, like, I want my calendar squares to say sort of equally sized. So, I wanted to limit myself to only showing four or five events per calendar day. And so, I added a little link at the bottom of the calendar day that says, you know, "See more." And when you click that link, it does some Turbo stuff, and it pulls in other events so that you can now sort of expand it to get the whole day. So, it's just a little bit of interactivity that you kind of get for free with Turbo just by wrapping a particular HTML tag around it and having the Turbo library loaded. STEPHANIE: That's cool. I'm excited to try it out next time I'm working on a Rails project that just needs a little bit of that interactivity, you know, just to make that experience a little bit richer. And it seems like a really good, like, low-effort way to add some of those enhancements. Based on what you described, it sounds really easy. JOËL: Yeah, I was impressed with just how low effort it all was, which is what you want, right? It works out of the box. So, for anyone who's kind of curious about it, Turbo Frames is the little bit that I used, and it worked really well. Oh, something I'm actually excited about it as well; it plays nicely with clients that have disabled JavaScript. So, this link that I click to pull in the rest of the events, if somebody has JavaScript disabled, or if they command-click or control-click to open in a new tab, it doesn't just do nothing like it would often do in many sort of front-end framework-y places that have hijacked the URL click handler. Instead, it actually opens up the full list of items in a new page, just as if you'd clicked a normal link. So, it really gives you that progressive enhancement feel where I can click a link, and it goes to another page with a list of all the 30 events if I don't have JavaScript. But if I do, maybe I get a slightly better experience where, instead of taking me to a new page, it just expands the list, and I get to see the full list. So, it plays nicely on both sides. STEPHANIE: That's really cool. As someone who's just starting to dabble in some alternative browsers outside of the main popular ones [chuckles], I have noticed how many websites do not work for me anymore [laughs]. And that sounds, like, nice from a user perspective. JOËL: So, other than dabbling with the new browsers, what's new in your world? STEPHANIE: A few weeks ago, I talked about [laughs] sitting more at my desk and, you know, various incentives that I gave myself to do that. And I'd like to say that I've been doing a pretty good job [laughs]. So, what's new in my world is that I've followed up on my commitment to sit at my desk more, feel a little bit more organized in my workday. And that's especially true because the birds have finally discovered my bird feeder [laughs]. JOËL: Oh, that's really cool. STEPHANIE: There were a few weeks where I was not really getting any visitors, and, you know, I was just like, when are they going to come and eat this delicious birdseed that I've [laughs] put out for them? And it seems like a flock of chickadees that normally like to hang out on the apple tree in my backyard have figured out this new source of food, and they'll sometimes, five of them at a time, will come, and sometimes they even fight [laughs] to get on the ledge to hang out at the bird feeder. And yeah, it turns out that the six pounds of bird feed that I bought, I'll start to turn through [laughs] that a little bit quicker now, so I'm excited about that and just to also see other birds and species come and go as time goes on. So, that's been an exciting new development. JOËL: So, the six pounds of birdseed might not last you through the winter. STEPHANIE: I was debating between six pounds and, like, a 20-pound bag [laughs], which that would have been a lot. And so far, I think the six pounds has been serving me well. We'll see how long it lasts, but yeah, it's finally starting. I might have to refill it soon, so, you know, I was hopefully not going to have to store all that bird feed [laughs] just, like, in my house for a long time. JOËL: Any birds that have shown up that have been particularly fun to watch or that are maybe your favorites? STEPHANIE: I mentioned the chickadees because they seem to come as a group, and I really like watching them interact with each other. It's just kind of like bird TV, you know, it's not just a single bird. It's just watching these animals that are a collective do their thing. And I've been enjoying that a lot. JOËL: Now I'm just imagining a reality TV but the Chickadee edition. STEPHANIE: Oh yeah, definitely. I know some people put, like, cameras at their bird feeders to either live stream, which is funny because most of the time, there's nothing happening [laughs]. Usually, the birds are really in and out. Or they'll have, like, a really fancy camera to take, like, really beautiful up-close photos. There's a blog that I discovered recently where someone posts about the birds that visit them at their place in Michigan. I'll link to it in the show notes, but it's really cool to see these, like, up-close and personal photos of basically the bird's mouth. Sometimes, they're open [laughs], so you can see right in them. I don't know; maybe there's a time where I'll get so into it that I'll create my own bird feeder blog. JOËL: Well, if you do, you should definitely share it with the listeners on the podcast. Speaking of listeners on the podcast, we've recently had a listener question from Edward that I thought was a really interesting topic, and I wanted to take a whole episode to dig into. And Edward asks about the concept of a spike. Sometimes, we're asked to investigate a complex new feature, and you might want to do some evaluation on the feasibility and complexity and build out just enough of it to make a well-informed opinion. And ideally, you're doing that in a way that reduces risk of spending too much time with unproven impact. The problem is that in any reasonably complex codebase, that investigation work can be most of the work needed to build the feature. And Edward gives an example: if you're adding a system admin role, the core of the work is adding a new role with all of the abilities, but the real work is ensuring that it interacts with the entire system in the appropriate way. So, how do you manage making sure that you're doing spikes well? And Edward asks if this is something that we've experienced a sort of feeling that we're doing 90% of the work in the spike. He also asks, does this say something about the codebase that you're working on? If it's hard to spike in it, does that say something about the underlying codebase, or are we just all doing spikes wrong? So yeah, I'm curious, Stephanie: do you occasionally spike things out in code on your projects? STEPHANIE: Yeah, I do. I think one piece that was left a little bit unsaid is that I think spiking usually comes up when the team can't really estimate how long a task will take, you know, assuming that you use estimates on your team [chuckles]. That calls for a spike ticket, right? And someone will spend some time. And I think on some teams, this is usually time-boxed as well to maybe do a proof of concept or, yeah, do some of that initial exploration. JOËL: Before we go too deep, I think it's probably useful to define spike in that I think it's a little bit easy and probably varies from team to team and even from a developer to developer. I think, for me, when I think of a spike, it's throwaway work. The code that I write will not get shipped, and this is not code that will just get improved later. It is entirely throwaway work. And the purpose of it is to learn something about the project that's being done. Typically, it's in a sort of de-risking fashion, so to say, look, we've got a feature that's got a lot of unknowns in it. And if we commit to it right now or we start investing time into it, it could become a bit of a time pit. Let's try to answer some questions about it. Let's try to resolve some of those unknowns so that we can better make decisions around maybe estimation, but maybe even just prioritization. If this seems like something that would be really challenging to do, maybe we don't want to prioritize it this quarter. Is that similar to how you think of spikes, or do you have a different sort of definition of it? STEPHANIE: Yeah, I am glad you mentioned that it's throwaway work. I think I was a little hesitant to commit to that definition with conviction because even based off of what Edward was saying, there's kind of, like, maybe different ideas about that or different expectations. But I sometimes think that, depending, spiking doesn't even necessarily need to lead to code. Like, it could just be answering questions. And so, at the same time, I think it is, I like what you said, work that helps you learn more about the system, whether or not there's some code written as, like, a potential path at the end of it. JOËL: Interesting. So, you would put some things that don't involve code at all in the spike bucket. STEPHANIE: I think there have been times where I've done a spike, and I've not coded out anything, but I've answered some questions, and I've left comments about unearthing some of the uncertainty that led us to want to explore the idea in the first place. Then, again, I also have gone down the path of, like, trying out a solution and maybe even multiple and then evaluating afterwards which ones I think were more suitable. So, it could mean both. I think that is actually something that's within the power of whoever is assigned this work to determine whatever is valuable to them in order to get enough information to figure out how you want to move forward. JOËL: Another element of spikes that I think is often implied is that because this is throwaway work, you're not necessarily putting in all the work to make everything sort of clean, or well-structured, or reusable, or anything like that. So, it's quite possible that you would not even test this. You might not break this out into objects in the way that you would if this had to be reused. You might have duplication all over, and that's okay because the purpose of this code is not to be sort of production-grade; it's to answer some questions, and then you're going to throw it away and, using those answers, build something correctly. STEPHANIE: Yeah, I think that's true. And it's kind of an interesting distinction from, you know, what you might consider your regular work in which the expectation is that it will be shipped [chuckles]. And there's also some amount of conflating the two, I think because if, you know, you and I are saying like, yeah, like, this exploration should be standalone, and it is not going to be used to be built on top of necessarily, there is some amount of revisiting. And you're not starting from scratch because you have an idea, but you are starting fresh if you will. And so, you know, when you are doing that spiking, I think it allows you to move a little bit faster, but that doesn't mean that the work is, like, any X percent [laughs] done at the end of it. JOËL: The work is still kind of, I guess, 0% done, again, because this is throwaway code, in our definition of a spike anyway. Would you distinguish between the terms spike and prototype? STEPHANIE: Oh, interesting. My initial reaction is that a prototype would then be user-tested [laughs] in some way. Like, the point is to then show someone and then get them interacting with it, any initial reactions from that. Whereas a spike is really for the developer and maybe the team to discuss. JOËL: I like that distinction. I definitely think that a spike, for me, is purely technical. We're not spiking out a feature by putting a thing live in production behind a feature flag, showing it to 10% of users, and seeing how they respond to that. That's not a spike. So, I think something a little bit more like that, or where you're showing things maybe to users, or you're wanting to do maybe some user testing with something. And it can be throwaway code still. I think now you're starting to get something more that you would call a prototype. So, I like that distinction of, is this sort of internal or external? But in the way they're used, they can often be similar, and that oftentimes both will sort of...they're built to be as cheap as possible to answer the questions you're trying to get answered, whether that's from a user or just technical reasons. And so, the whole thing can be a little bit of smoke and mirrors, a little bit of duct tape and toothpicks, as long as you only have...like, the only solid parts you need are the parts that are going to help you answer your question. And so, any hack or cheat you can get to to bypass everything else is time you've saved, and that's a good thing. STEPHANIE: Oh, I'm very curious about this idea of time saved because I think sometimes an underappreciated outcome of a spike is what not to do or is choosing not to do something. And it can feel not great to have spent hours or even days exploring a path just to realize that it's not worth it. I'm curious, like, when you know to stop and also, how you get other people kind of onboard that even just figuring out an initial idea was not a viable solution, how that could be a valuable insight to the rest of the team. JOËL: Something that I think can be really useful is before you even start spiking out something, write a list of questions that you're trying to answer with this code, and then don't let yourself get distracted. Write the minimum amount of code that will allow you to answer those questions. So, maybe that is a question around, is it possible to connect this external API to our systems? There are some questions around, like, how credentials and things will work or how complex that will be. It might be a question around, like, maybe there's even, like, a performance thing. We want to talk to an external system and, you know, the responses back need to be within a certain amount of time. Otherwise, this whole approach where we're going to try to fetch data live is not feasible. So, the answer we need there is, can we do it live, or do we need to consider some sort of background fetching, or caching approach, or something like that? So, write the minimum amount of code that it would take to do that. And maybe the minimum amount of code, like you said, is not even really code. Maybe it's a script or even just trying out some curl commands and timing them at the command line. It could be a lot of things. But I think having a list of questions up front really helps you focus on the purpose of the spike. And I think it helps me a little bit as well with emotional attachment in that success is not necessarily coming to a yes on all of those questions. It is having an answer, going from question mark to some answer. So, if I can answer that question, if I can find even a clever way to answer that question faster, that is success. I have done a good job with my spike. STEPHANIE: I like that a lot. I think some people might struggle with spikes because they're so ambiguous. And if it's just, like, explore this potential feature, or, like, maybe not even that, but even saying, like, we want to build this admin role, to use Edward's example. And to constrain it to how should we do that, it already kind of guides the spike in a certain direction that may or may not be exactly what you're looking for. And so, there's some value in figuring out what questions to ask with the product team, even to get alignment on what the purpose of this task is. And, you know, this is true of regular feature work, too. When those decisions have kind of already been made about what we're working on without a lot of input from developers who will be working on it, it can be really hard to, like, go back and be like, "Oh, actually, that's not really possible." But if the questions are like, "Is this possible?" or like, what it costs to do this, I think it prevents some of that friction and misalignment that might be had when the outcome of a spike turns out to be maybe not what someone wants to hear. JOËL: And I think the questions you ask don't necessarily have to be yes or no questions. They could be some sort of list, right? It could be, look, we're looking at two different implementations or two general approaches, families of solutions for our super admin role. What are the trade-offs of each? And so, a spike might be exploring. Can we come up with a list of pros and cons for each approach? And maybe some of them we just know from experience at developing, but maybe some of them might involve actually doing a little bit of work to play out the pros and cons. Maybe that's in our app. Maybe that's even spinning up a little app on the side, right? If we're comparing maybe two gems or something like that to see how we feel about throwing a few different scenarios and exploring edge cases. So, the questions don't need to be straight-up yes or no. So, you mentioned earlier the idea that sometimes one developer might do the spike, and then another one might do the actual work, maybe inspired by the answers that were on that spike. And I think that can lead to some really interesting dynamics, especially if the developer who did the first spike has done kind of, like, what Edward describes, what feels like 90% of the feature. It may be not so great code quality. And then this is a branch on GitHub, and they're like, "Okay, do the rest. Make it good. I've already explored the possibilities here," and then you're the developer who has to pick that up. Have you ever experienced that? And if so, how do you feel picking up a ticket like that? STEPHANIE: Yeah, I have experienced it, and I think there is always something lost when that happens when you are not the person who did the research. And then having to just go from whatever was left in the notes or from the code and, you know, I don't know how feasible it is for whoever spiked to always be doing the implementing, but I certainly end up having a lot of questions, I think. Like, you can't document or even code out, like, every single thing you learned in that process, right? There's always from big to small decisions or alternatives considered that won't make it into however that communication or expression or knowledge transfer happens. And I think the two choices that I have as a developer picking that up is either to just trust [laughs] that the work the other person did is taking me down a good path or to spend more time rebuilding some of that context and making some of my own evaluations along the way and deciding for myself whether I'm like, oh yeah, this is a good idea, or maybe, like, I might change something here. So, I think that there is some time lost, too. And I think that's a really good thing to point out when someone might think like, oh, this is mostly done. That's kind of my first reaction in terms of the context loss in an exchange like that. JOËL: Do you feel like this is a situation where you would want to have the same developer do both the spike and the final implementation? Or is this maybe a situation where spikes aren't being done correctly, and maybe a branch with some code that's kind of half-written is maybe the wrong artifact to hand off from one developer to the other? STEPHANIE: Oh, that's really interesting about if that's the wrong artifact to hand off because it could be misleading. Maybe it's not always, and maybe there's some really great code that comes out of it if someone builds on top of a work-in-progress branch or a spike branch. Honestly, I think, and I haven't even really gotten to experience this all too much because maybe there is some perception that it's backtracking or, you know, it's more work or more time, but it would be really cool for whoever had spiked it to then bring someone along to pair on it and start fresh, like we mentioned, where they're kind of coming to each decision to be made with an idea, but it's not necessarily set in stone, right? There could be that discussion. It could be, like, a generative experience to either refine that code that had initially been spiked out or discover new things along the way. It's not like the outcome has already been decided because of the spike. It is information, and that's that. JOËL: And we on this podcast are very pro-discovering new things along the way. I think sometimes as a developer, if I get sort of a, you know, maybe a 90% branch done that's get passed on to me from somebody else who did a spike, it feels a little bit like the finish the rest of the owl meme, except that now I'm not even, like, just trying to follow a tutorial. Just somebody did the first couple of circles and then is like, "Oh yeah, you finish the rest of the owl. I did the hard work. You just need to polish it up." On the one hand, it's like, dude, if you're, like, doing 90%, you may as well finish it. I don't want to just be polishing somebody else's work. And, you know, oftentimes, it might feel like it's done 90% of the time, but it's actually, like, there's a lot of edge cases and nuance that have not been handled. And, you know, a spike is meant to be throwaway work to start with. So, I felt like those sorts of handoffs often, I don't know, they don't sit with me well. STEPHANIE: Yeah. You could also come in and be like, this doesn't even look like an owl at all [laughs]. JOËL: I feel like maybe in my ideal world, a branch with partly written code is, I guess, an intermediate artifact that might be useful to show. But what I really want from a spike is answers to questions that will allow me, when I build the thing from scratch to make intelligent decisions. So, probably what I want out of a spike is something that's closer to documentation, a list of questions that we were asking, and then the answers we came to by doing the spike work. And that might be maybe a list of trade-offs, or maybe we didn't really know the correct endpoints from this undocumented API, and we tried some stuff, and we, like, figured out what endpoints we needed, or what the shape of the JSON payload needed to be, things like that. Maybe we tried a couple of different implementations, or we did some exploration around, like, what gem we'd like to use, and we have a recommendation for a gem. Those are all, I think, very concrete outcomes from a spike that I can then use when I'm building it from scratch. And I'm not just, like, branching off your branch or having it open in another browser and copy-pasting snippets while trying to, like, add some testing and maybe modularizing it a little bit. I think that leads to probably a better outcome for the person who's doing the spike because they have a tighter scope and also a better outcome for me, who's then trying to build that feature correctly from the ground up. I think that would be my sort of ideal workflow. STEPHANIE: While you were saying that, I thought about how a lot of those points sounded like requirements for a feature. And that, I think, is also a good outcome when a spike then leads to more concrete requirements because those are all decisions that were thought through, right? And even better is if that also documents things that were tried and the trade-offs that came with them or, like, the reasons why they were less viable or not ideal for that added context because that is also work that happened [laughs] and should be captured so someone can know that that might not be time they need to spend on that. I am really interested in one piece that we haven't quite touched on is the complexity of the app and what it means for spiking to be a challenge because of the complexity of the app. JOËL: Yeah. And I think sort of inherent in there is that maybe the idea that if you have a really complex app, it sort of forces you to go to the 90% of the work done in order to successfully answer the questions you wanted to answer with your spike in a way that maybe a better-structured app would not. Do you think that's true? STEPHANIE: Well, I actually think that if the app is complex, you're actually seeing that affect all parts of feature development, not just spiking, where everything takes longer [laughs] because you maybe feel less confident. You're nervous about breaking something. Edward called the real work ensuring that it interacts with the entire system correctly, and that's true of, I think, just software development in general. And so, I wonder if, you know, spiking happens to be one way that it manifests, but if there are signals that it's affecting, you know, all parts of your workflow. JOËL: There definitely is a cost, right? Complex software imposes costs everywhere. In some way, I think maybe spiking is attempting to get around some of those, in that there are some decisions that we can just say, you know what? We'll build the feature, and we'll just kind of figure it out as we go along, and we'll, like, build the thing. Spiking attempts to say, look, let's not build the whole thing. Let's fake out a bunch of parts because, really, we have a big question that we want to answer about a thing that is three steps down, you know. And maybe the question is, look, we're trying to build the super admin role, and we know it's got all these, like, edge cases we need to deal with. Maybe we need a list of the edge cases, and maybe that's how we, like, try to drive them out. But maybe this is a, hey, do we want to go with more of a, like, a role hierarchy inheritance-based approach, or do we want to go with some sort of escalating defaults? Or whatever the couple of different strategies you might want to do. And the spike might be trying to answer the question, how can we, as cheaply as possible while doing the minimum amount of work, sort of explore which of these implementations works best? And in a complex system, is it possible to get to the answer to those questions without building out 90% of the feature itself? I think, going to what you said, you might have to do more work if it's a complex system. But I would also encourage everyone to go absolute minimalist, like, keep your goal in mind: what is the question you're trying to answer? And then ruthlessly cut everything you need to get to your point where you can answer that question. Do you need to hard code? Do you need to metaprogram? Do you need to do just, like, the worst, dirtiest code that you've ever written? That's okay because, like, the implementation does not matter. The fact that you're not exercising the full system does not matter, as long as the part that you're trying to exercise and answer your questions does get used. STEPHANIE: Yeah, I like that a lot. And I wonder if the impulse to want to spike something is coming out of nervousness about how complicated the ask is. And it's like, well, I don't want to tell you that it's going to take a long time because this app is extremely complex, and everything takes a long time. You know, it's like not wanting to face that hard question of either we need to just set our expectations that things take longer, or we need to make some kind of change to make that easier to work with. And that is a lot of thought and effort. And so, it's kind of an answer to be like, well, like, let me spike this out and then see [laughs]. And so it may be a way to appease someone making a request for a feature. I don't know; I'm perhaps projecting a little bit here [chuckles]. But it could also be an important question to ask yourself if you find your team, like, needing to lean on spikes a lot because you just don't know. JOËL: That's really interesting because I think that maybe connects to a recent episode we did on breaking features down into smaller chunks. Spikes can often manifest, or the need for a spike can often manifest when you've got a larger, less well-defined feature that you want to do. So, sometimes, breaking things into smaller pieces will help you have something that's a little bit more well-defined that you feel confident jumping into without doing a spike. Or maybe the act of trying to split this sort of large, undefined task into smaller pieces will reveal questions that need to be answered and say, look, I don't know where the seam should be, where to split this task because I don't know the answer to this one question. If I could know the answer to this one question, I would know where to split this feature. That's your spike right there. Do the minimum amount of code to answer that one question, and then you can split your feature and confidently work on the two smaller pieces. And I think that's a win for everyone. STEPHANIE: Yeah. And you can listen back to our vertical slice episode [laughs] for some inspiration on that. JOËL: On that note, shall we wrap up? STEPHANIE: Let's wrap up. Show notes for this episode can be found at bikeshed.fm. JOËL: This show has been produced and edited by Mandy Moore. STEPHANIE: If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter. STEPHANIE: Or reach both of us at hosts@bikeshed.fm via email. JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week. ALL: Byeeeeeeeee!!!!!!! AD: Did you know thoughtbot has a referral program? If you introduce us to someone looking for a design or development partner, we will compensate you if they decide to work with us. More info on our website at: tbot.io/referral. Or you can email us at referrals@thoughtbot.com with any questions.

Stephanie shares her task of retiring a small, internally-used link-shortening app. She describes the process as both celebratory and a bit mournful. Meanwhile, Joël discusses his deep dive into ActiveRecord, particularly in the context of debugging. He explores the complexities of ActiveRecord querying schemas and the additional latency this introduces. Together, the hosts discuss the nuances of package management systems and their implications for developers. They touch upon the differences between system packages and language packages, sharing personal experiences with tools like Homebrew, RubyGems, and Docker. Transcript: JOËL: Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Joël Quenneville. STEPHANIE: And I'm Stephanie Minn. And together, we're here to share a bit of what we've learned along the way. JOËL: So, Stephanie, what's new in your world? STEPHANIE: So, this week, I got to have some fun working on some internal thoughtbot work. And what I focused on was retiring one of our just, like, small internal self-hosted on Heroku apps in favor of going with a third-party service for this functionality. We basically had a tiny, little app that we used as a link-shortening service. So, if you've ever seen a tbot.io short link out in the world, we were using our just, like, an in-house app to do that, you know, but for various reasons, we wanted to...just it wasn't worth maintaining anymore. So, we wanted to just use a purchased service. But today, I got to just, like, do the little bit of, like, tidying up, you know, in preparation to archive a repo and kind of delete the app from Heroku, and I hadn't done that before. So, it felt a little bit celebratory and a little bit mournful even [laughs] to, you know, retire something like that. And I was pairing with another thoughtbot developer, and we used a pairing app called Tuple. And you can just send, like, fun reactions to each other. Like, you could send, like, a fire emoji [laughs] or something if that's what you're feeling. And so, I sent some, like, confetti when we clicked the, "I understand what deleting this app means on GitHub." But I joked that "Actually, I feel like what I really needed was a, like, a salute kind of like thank you for your service [laughs] type of reaction." JOËL: I love those moments when you're kind of you're hitting those kind of milestone-y moments, and then you get to send a reaction. I should do that more often in Tuple. Those are fun. STEPHANIE: They are fun. There's also a, like, table flip reaction, too, is one that I really enjoy [laughs], you know, you just have to manifest that energy somehow. And then, after we kind of sent out an email to the company saying like, "Oh yeah, we're not using our app anymore for link shortening," someone had a great suggestion to make our archived repo public instead of private. I kind of liked it as a way of, like, memorializing this application and let community members see, you know, real code in a real...the application that we used here at thoughtbot. So, hopefully, if not me, then someone else will be able to do that and maybe publish a little blog post about that. JOËL: That's exciting. So, it's not currently public, the repo, but it might be at some point in the future. STEPHANIE: Yeah, that's right. JOËL: We'll definitely have to mention it on a future episode if that happens so that people following along with the story can go check out the code. STEPHANIE: So, Joël, what's new in your world? JOËL: I've been doing a deep dive into how ActiveRecord works. Particularly, I am debugging some pretty significant slowdowns in querying ActiveRecord models that are backed not by a regular Postgres database but instead a Snowflake data warehouse via an ODBC connection. So, there's a bunch of moving pieces going on here, and it would just take forever to make any queries. And sure, the actual reported query time is longer than for a local Postgres database, but then there's this sort of mystery extra waiting time, and I couldn't figure out why is it taking so much longer than the actual sort of recorded query time. And I started digging into all of this, and it turns out that in addition to executing queries to pull actual data in, ActiveRecord needs to, at various points, query the schema of your data store to pull things like names of tables and what are the indexes and primary keys and things like that. STEPHANIE: Wow. That sounds really cool and something that I have never needed to do before. I'm curious if you noticed...you said that it takes, I guess, longer to query Snowflake than it would a more common Postgres database. Were you noticing this performance slowness locally or on production? JOËL: Both places. So, the nice thing is I can reproduce it locally, and locally, I mean running the Rails app locally. I'm still talking to a remote Snowflake data warehouse, which is fine. I can reproduce that slowness locally, which has made it much easier to experiment and try things. And so, from there, it's really just been a bit of a detective case trying to, I guess, narrow the possibility space and try to understand what are the parts that trigger slowness. So, I'm printing timestamps in different places. I've got different things that get measured. I've not done, like, a profiling tool to generate a flame graph or anything like that. That might have been something cool to try. I just did old-school print statements in a couple of places where I, like, time before, time after, print the delta, and that's gotten me pretty far. STEPHANIE: That's pretty cool. What do you think will be an outcome of this? Because I remember you saying you're digging a little bit into ActiveRecord internals. So, based on, like, what you're exploring, what do you think you could do as a developer to increase some of the performance there? JOËL: I think probably what this ends up being is finding that the Snowflake adapter that I'm using for ActiveRecord maybe has some sort of small bug in it or some implementation that's a little bit too naive that needs to be fine-tuned. And so, probably what ends up happening here is that this finishes as, like, an open-source pull request to the Snowflake Adapter gem. STEPHANIE: Yeah, that's where I thought maybe that might go. And that's pretty cool, too, and to, you know, just be investigating something on your app and being able to make a contribution that it benefits the community. JOËL: And that's what's so great about open source because not only am I able to get the source to go source diving through all of this, because I absolutely need to do that, but also, then if I make a fix, I can push that fix back out to the community, and everybody gets to benefit. STEPHANIE: Cool. Well, that's another thing that I look forward to hearing more on the development of [laughs] later if it pans out that way. JOËL: One thing that has been interesting with this Snowflake work is that there are a lot of moving parts and multiple different packages that I need to install to get this all to work. So, I mentioned that I might be doing a pull request against the Snowflake Adapter for ActiveRecord, but all of this talks through a sort of lower-level technology protocol called ODBC, which is a sort of generic protocol for speaking to data stores, and that actually has two different pieces. I had to install two different packages. There is a sort of low-level executable that I had to install on my local dev machine and that I have to install on our servers. And on my Mac, I'm installing that via Homebrew, which is a system package. And then to get Ruby bindings for that, there is a Ruby gem that I install that allows Ruby code to talk to ODBC, and that's installed via RubyGems or Bundler. And that got me thinking about sort of these two separate ecosystems that I tend to work with every day. We've got sort of the system packages and the, I don't know what you want to call them, language packages maybe, things like RubyGems, but that could also be NPM or whatever your language of choice is, and realizing that we kind of have things split into two different zones, and sometimes we need both and wondering a little bit about why is that difference necessary. STEPHANIE: Yeah, I don't have an answer to that [laughs] question right now, but I can say that that was an area that really tripped me up, I think, when I was first a fledgling developer. And I was really confused about where all of these dependencies were coming from and going through, you know, setting up my first project and being, like, asked to install Postgres on my machine but then also Bundler, which then also installs more dependencies [laughs]. The lines between those ecosystems were not super clear to me. And, you know, even now, like, I find myself really just kind of, like, learning what I need to know to get by [laughs] with my day-to-day work. But I do like what you said about these are kind of the two main layers that you're working with in terms of package management. And it's really helpful to have that knowledge so you can troubleshoot when there is an issue at one or the other. JOËL: And you mentioned Postgres. That's another one that's interesting because there are components in both of those ecosystems. Postgres itself is typically installed via a system package manager, so something like Homebrew on a Mac or apt-get on a Linux machine. But then, if you're interacting with Postgres in a Ruby app, you're probably also installing the pg gem, which are Ruby's bindings for Postgres to allow Ruby to talk to Postgres, and that lives in the package ecosystem on RubyGems. STEPHANIE: Yeah, I've certainly been in the position of, you know, again, as consultants, we oftentimes are also setting up new laptops entirely [laughs] like client laptops and such and bundling and the pg gem is installed. And then at least I have, you know, I have to give thanks to the very clear error message that [laughs] tells me that I don't have Postgres installed on my machine. Because when I mentioned, you know, troubleshooting earlier, I've certainly been in positions where it was really unclear what was going on in terms of the interaction between what I guess we're calling the Ruby package ecosystem and our system level one. JOËL: Especially for things like the pg gem, which need to compile against some existing libraries, those always get interesting where sometimes they'll fail to compile because there's a path to some C compiler that's not set correctly or something like that. For me, typically, that means I need to update the macOS command line tools or the Xcode command line tools; I forget what the name of that package is. And, usually, that does the trick. That might happen if I've upgraded my OS version recently and haven't downloaded the latest version of the command line tools. STEPHANIE: Yeah. Speaking of OS versions, I have a bit of a story to share about using...I've never said this name out loud, but I am pretty sure that it would just be pronounced as wkhtmltopdf [laughs]. For some reason, whenever I see words like that in my brain, I want to, like, make it into a pronounceable thing [laughs]. JOËL: Right, just insert some vowels in there. STEPHANIE: Yeah, wkhtmltopdf [laughs]. Anyway, that was being used in an app to generate PDF invoices or something. It's a pretty old tool. It's a CLI tool, and it's, as far as I can tell, it's been around for a long time but was recently no longer maintained. And so, as I was working on this app, I was running into a bug where that library was causing some issues with the PDF that was generated. So, I had to go down this route of actually finding a Ruby gem that would figure out which package binary to use, you know, based off of my system. And that worked great locally, and I was like, okay, cool, I fixed the issue. And then, once I pushed my change, it turns out that it did not work on CI because CI was running on Ubuntu. And I guess the binary didn't work with the latest version of Ubuntu that was running on CI, so there was just so many incompatibilities there. And I was wanting to fix this bug. But the next step I took was looking into community-provided packages because there just simply weren't any, like, up-to-date binaries that would likely work with these new operating systems. And I kind of stopped at that point because I just wasn't really sure, like, how trustworthy were these community packages. That was an ecosystem I didn't know enough about. In particular, I was having to install some using apt from, you know, just, like, some Linux community. But yeah, I think I normally have a little bit more experience and confidence in terms of the Ruby package ecosystem and can tell, like, what gems are popular, which ones are trustworthy. There are different heuristics I have for evaluating what dependency to pull in. But here I ended up just kind of bailing out of that endeavor because I just didn't have enough time to go down that rabbit hole. JOËL: It is interesting that learning how to evaluate packages is a skill you have to learn that varies from package community to package community. I know that when I used to be very involved with Elm, we would often have people who would come to the Elm community from the JavaScript community who were used to evaluating NPM packages. And one of the metrics that was very popular in the JavaScript community is just stars on GitHub. That's a really important metric. And that wasn't really much of a thing in the Elm community. And so, people would come and be like, "Wait, how do I know which package is good? I don't see any stars on GitHub." And then, it turns out that there are other metrics that people would use. And similarly, you know, in Ruby, there are different ways that you might use to evaluate Ruby gems that may or may not involve stars on GitHub. It might be something entirely different. STEPHANIE: Yeah. Speaking of that, I wanted to plug a website that I have used before called the Ruby Toolbox, and that gives some suggestions for open-source Ruby libraries of various categories. So, if you're looking for, like, a JSON parser, it has some of the more popular ones. If you're looking for, you know, it stores them by category, and I think it is also based on things like stars and forks like that, so that's a good one to know. JOËL: You could probably also look at something like download numbers to see what's popular, although sometimes it's sort of, like, an emergent gem that's more popular. Some of that almost you just need to be a little bit in the community, like, hearing, you know, maybe listening to podcasts like this one, subscribing to Ruby newsletters, going to conferences, things like that, and to realize, okay, maybe, you know, we had sort of an old staple for JSON parsing, but there's a new thing that's twice as fast. And this is sort of becoming the new standard, and the community is shifting towards that. You might not know that just by looking at raw stats. So, there's a human component to it as well. STEPHANIE: Yeah, absolutely. I think an extension of knowing how to evaluate different package systems is this question of like, how much does an average developer need to know about package management? [laughs] JOËL: Yeah, a little bit to a medium amount, and then if you're writing your own packages, you probably need to know a little bit more. But there are some things that are really maybe best left to the maintainers of package managers. Package managers are actually pretty complex pieces of software in terms of all of the dependency management and making sure that when you say, "Oh, I've got Rails, and this other gem, and this other gem, and it's going to find the exact versions of all those gems that play nicely together," that's non-trivial. As a sort of working developer, you don't need to know all of the algorithms or the graph theory or any of that that underlies a package manager to be able to be productive in your career. And even as a package developer, you probably don't need to really know a whole lot of that. STEPHANIE: Yeah, that makes sense. I actually had referred to our internal at thoughtbot here, our kind of, like, expectations for skill levels for developers. And I would say for an average developer, we kind of just expect a basic understanding of these more complex parts of our toolchain, I think, specifically, like, command line tools and package management. And I think I'd mentioned earlier that, for me, it is a very need-to-know basis. And so, yeah, when I was going down that little bit of exploration around why wkhtmltopdf [chuckles] wasn't working [chuckles], it was a bit of a twisty and turning journey where I, you know, wasn't really sure where to go. I was getting very obtuse error messages, and, you know, I had to dive deep into all these forums [laughs] for all the various platforms [laughs] about why libraries weren't working. And I think what I did come away with was that like, oh, like, even though I'm mostly working on my local machine for development, there was some amount of knowledge I needed to have about the systems that my CI and, you know, production servers are running on. The project I was working on happened to have, like, a Docker file for those environments, and, you know, kind of knowing how to configure them to install the packages I needed to install and just knowing a little bit about the different ways of doing that on systems outside of my usual daily workflows. JOËL: And I think that gets back to some of the interesting distinctions between what we might call language packages versus system packages is that language packages more or less work the same across all operating systems. They might have a build step that's slightly different or something like that, but system packages might be pretty different between different operating systems. So, development, for me, is a Mac, and I'm probably installing system packages via something like Homebrew. If I then want that Rails app to run on CI or some Linux server somewhere, I can't use Homebrew to install things there. It's going to be a slightly different package ecosystem. And so, now I need to find something that will install Postgres for Linux, something that will install, I guess, wkhtmltopdf [laughs] for Linux. And so, when I'm building that Docker file, that might be a little bit different for Mac versus for...or I guess when you run a Docker file, you're running a containerized system. So, the goal there is to make this system the same everywhere for everyone. But when you're setting that up, typically, it's more of a Linux-like system. And so running inside the Docker container versus outside on the native Mac might involve a totally different set of packages and a different package tool. As opposed to something like Bundler, you've got your gem file; you bundle install. It doesn't matter if you're on Linux or macOS. STEPHANIE: Yes, I think you're right. I think we kind of answered our own question at the top of the show [laughs] about differences and what do you need to know about them. And I also like how you pointed out, oh yeah, like, Docker is supposed to [laughs], you know, make sure that we're all developing in the same system, essentially. But, you know, sometimes you have different use cases for it. And, yeah, when you were talking about installing an application on your native Mac and using Homebrew, but even, you know, not everyone even uses Homebrew, right? You can install manually [laughs] through whatever official installer that application might provide. So, there's just so many different ways of doing something. And I had the thought that it's too bad that we both [chuckles] develop on Mac because it could be really interesting to get a Linux user's perspective in here. JOËL: You mentioned not installing via Homebrew. A kind of glaring example of that in my personal setup is that I use Postgres.app to manage Postgres on my machine rather than using Homebrew. I've just...over the years, the Homebrew version every time I upgrade my operating system or something, it's just such a pain to update, and I've lost too many hours to it, and Postgres.app just works, and so I've switched to that. Most other things, I'll use the Homebrew version, but Postgres it's now Postgres.app. It's not even a command line install, and it works fine for me. STEPHANIE: Nice. Yeah. That's interesting. That's a good tip. I'll have to look into that next time because I have also certainly had to just install so many [laughs] various versions of Postgres and figure out what's going on with them every time I upgrade my OS. I'm with you, though, in terms of the packages world I'm looking for, it works [laughs]. JOËL: So, you'd mentioned earlier that packages is sort of an area that's a bit of a need-to-know basis for you. Are there, like, particular moments in your career that you remember like, oh, that's the moment where I needed to, like, take some time and learn a little bit of the next level of packages? STEPHANIE: That's a great question. I think the very beginnings of understanding how package versions work when you have multiple projects on your machine; I just remember that being really confusing for me. When I started out, like, you know, as soon as I cloned my second repo [laughs], and was very confused about, like, I'm sure I went through the process of not installing gems using Bundler, and then just having so much chaos [laughs] wrecked in my development environment and, you know, having to ask someone, "I don't understand how this works. Like, why is it saying I have multiple versions of this library or whatever?" JOËL: Have you ever sudo gem installed a gem? STEPHANIE: Oh yeah, I definitely have. I can't [laughs], like, even give a good reason for why I have done it, but I probably was just, like, pulling my hair out, and that's what Stack Overflow told me to do. I don't know if I can recommend that, but it is [chuckles] one thing to do when you just are kind of totally stuck. JOËL: There was a time where I think that that was in the READMEs for most projects. STEPHANIE: Yeah, that's a really good point. JOËL: So, that's probably why a lot of people end up doing that, but then it tends to install it for your system Ruby rather than for...because if you're using something like Rbenv or RVM or ASDF to manage multiple Ruby versions, those end up being what's using or even Homebrew to manage your Ruby. It wouldn't be installing it for those versions of Ruby. It would be installing it for the one that shipped with your Mac. I actually...you know what? I don't even know if Mac still ships with Ruby. It used to. It used to ship with a really old version of Ruby, and so the advice was like, "Hey, every repo tells you to install it with sudo; don't do that. It will mess you up." STEPHANIE: Huh. I think Mac still does ship with Ruby, but don't quote me on that [laughter]. And I think that's really funny that, like, yeah, people were just writing those instructions in READMEs. And I'm glad that we've collectively [laughs] figured out that difference and want to, hopefully, not let other developers fall into that trap [laughs]. Do you have a particular memory or experience when you had to kind of level up your knowledge about the package ecosystem? JOËL: I think one sort of moment where I really had to level up is when I started really needing to understand how install paths worked, especially when you have, let's say, multiple versions of a gem installed because you have different projects. And you want to know, like, how does it know which one it's using? And then you see, oh, there are different paths that point to different directories with the installs. Or when you might have an executable you've installed via Homebrew, and it's like, oh yeah, so I've got this, like, command that I run on my shell, but actually that points to a very particular path, you know, in my Homebrew directory. But maybe it could also point to some, like, pre-installed system binaries or some other custom things I've done. So, there was a time where I had to really learn about how the path shell variable worked on a machine in order to really understand how the packages I installed were sometimes showing up when I invoked a binary and sometimes not. STEPHANIE: Yeah, that is another really great example that I have memories of [laughs] being really frustrated by, especially if...because, you know, we had talked earlier about all the different ways that you can install applications on your system, and you don't always know where they end up [laughs]. JOËL: And this particular memory is tied to debugging Postgres because, you know, you're installing Postgres, and some paths aren't working. Or maybe you try to update Postgres and now it's like, oh, but, like, I'm still loading the wrong one. And why does PSQL not do the thing that I think it does? And so, that forced me to learn a little bit about, like, under the hood, what happens when I type brew install PostgreSQL? And how does that mesh with the way my shell interprets commands and things like that? So, it was maybe a little bit of a painful experience but eye-opening and definitely then led to me, I think, being able to debug my setup much more effectively in the future. STEPHANIE: Yeah. I like that you also pointed out how it was interacting with your shell because that's, like, another can of worms, right? [laughs] In terms of just the complexity of how these things are talking to each other. JOËL: And for those of our listeners who are not familiar with this, there is a shell command that you can use called which, W-H-I-C-H. And you can prefix that in front of another command, and it will tell you the path that it's using for that binary. So, in my case, if I'm looking like, why is this PSQL behaving weirdly or seems to be using the old version, I can type 'which space psql', and it'll say, "Oh, it's going to this path." And I can look at it and be like, oh, it's using my system install of Postgres. It's not using the Homebrew one. Or, oh, maybe it's using the Homebrew install, not my Postgres.app version. I need to, like, tinker with the paths a little bit. So, that has definitely helped me debug my package system more than once. STEPHANIE: Yeah, that's a really good tip. I can recall just totally uninstalling everything [laughs] and reinstalling and fingers crossed it would figure out a route to the right thing [laughs]. JOËL: You know what? That works. It's not the, like, most precise solution but resetting your environment when all else fails it's not a bad solution. So, we've been talking a lot about what it's like to interact with a package ecosystem as developers, as users of packages, but what if you're a package developer? Sometimes, there's a very clear-cut place where to publish, and sometimes it's a little bit grayer. So, I could see, you know, I'm developing a database, and I want that to be on operating systems, probably should be a system-level package rather than a Ruby gem. But what if I'm building some kind of command line tool, and I write it in Ruby because I like writing Ruby? Should I publish that as a gem, or should I publish that as some kind of system package that's installed via Homebrew? Any opinions or heuristics that you would use to choose where to publish on one side or the other? STEPHANIE: As not a package developer [laughs], I can only answer from that point of view. That is interesting because if you publish on a, you know, like, a system repository, then yeah, like, you might get a lot more people using your tool out there because you're not just targeting a specific language's community. But I don't know if I have always enjoyed downloading various things to my system's OS. I think that actually, like, is a bit complicated for me or, like, I try to avoid it if I can because if something can be categorized or, like, containerized in a way that, like, feels right for my mental model, you know, if it's written in Ruby or something really related to things I use Ruby in, it could be nice to have that installed in my, like, systems RubyGems. But I would be really interested to hear if other people have opinions about where they might want to publish a package and what kind of developers they're hoping to find to use their tool. JOËL: I like the heuristic that you mentioned here, the idea of who the audience is because, yeah, as a Ruby developer who already has a Ruby setup, it might be easier for me to install something via a gem. But if I'm not a Ruby developer who wants to use the packages maybe a little bit more generic, you know, let's say, I don't know, it's some sort of command line tool for interacting with GitHub or something like that. And, like, it happens to be written in Ruby, but you don't particularly care about that as a user of this. Maybe you don't have Ruby installed and now you've got to, like, juggle, like, oh, what is RubyGems, and Bundler, and all this stuff? And I've definitely felt that occasionally downloading packages sort of like, oh, this is a Python package. And you're going to need to, like, set up all this stuff. And it's maybe designed for a Python audience. And so, it's like, oh, you're going to set up a virtual environment and all these things. I'm like, I just want your command line tools. I don't want to install a whole language. And so, sometimes there can be some frustration there. STEPHANIE: Yeah, that is very true. Before you even said that, I was like, oh, I've definitely wanted to download a command line tool and be like, first install [laughs] Python. And I'm like, nope, I'm bailing out of this. JOËL: On the other hand, as a developer, it can be a lot harder to write something that's a bit more cross-platform and managing all that. And I've had to deal a little bit with this for thoughtbot's Parity tool, which is a command-line tool for working with Heroku. It allows you to basically run commands on either staging or production by giving you a staging command and a production command for common Heroku CLI tasks, which makes it really nice if you're working and you're having to do some local, some development, some staging, and some production things all from your command line. It initially started as a gem, and we thought, you know what? This is mostly command line, and it's not just Rubyists who use Heroku. Let's try to put this on Homebrew. But then it depends on Ruby because it's written in Ruby. And now we had to make sure that we marked Ruby as a dependency in Homebrew, which meant that Homebrew would then also pull in Ruby as a dependency. And that got a little bit messy. For a while, we even experimented with sort of briefly available technology called Traveling Ruby that allowed you to embed Ruby in your binary, and you could compile against that. That had some drawbacks. So, we ended up rolling that back as well. And eventually, just for maintenance ease, we went back to making this a Ruby gem and saying, "Look, you install it via RubyGems." It does mean that we're targeting more of the Ruby community. It's going to be a little bit harder for other people to install, but it is easier for us to maintain. STEPHANIE: That's really interesting. I didn't know that history about Parity. It's a tool that I have used recently and really enjoyed. But yeah, I think I remember someone having some issues between installing it as a gem and installing it via Homebrew and some conflicts there as well. So, I can also see how trying to decide or maybe going down one path and then realizing, oh, like, maybe we want to try something else is certainly not trivial. JOËL: I think, in me, I have a little bit of the idealist and the pragmatist that fight. The idealist says, "Hey, if it's not, like, aimed for Ruby developers as a, like, you can pull this into your codebase, if it's just command line tools and the fact that it's written in Ruby is an implementation detail, that should be a system package. Do not distribute binaries via RubyGems." That's the idealist in me. The pragmatist says, "Oh, that's a lot of work and not always worth it for both the maintainers and sometimes for the users, and so it's totally okay to ship binaries as RubyGems." STEPHANIE: I was totally thinking that I'm sure that you've been in that position of being a user and trying to download a system package and then seeing it start to download, like, another language. And you're like, wait, what? [laughter] That's not what I want. JOËL: So, you and I have shared some of our heuristics in the way we approach this problem. Now, I'm curious to hear from the audience. What are some heuristics that you use to decide whether your package is better shipped on RubyGems versus, let's say, Homebrew? Or maybe as a user, what do you prefer to consume? STEPHANIE: Yes. And speaking of getting listener feedback, we're also looking for some listener questions. We're hoping to do a bit of a grab-bag episode where we answer your questions. So, if you have anything that you're wanting to hear me and Joël's thoughts on, write us at hosts@bikeshed.fm. JOËL: On that note, shall we wrap up? STEPHANIE: Let's wrap up. Show notes for this episode can be found at bikeshed.fm. JOËL: This show has been produced and edited by Mandy Moore. STEPHANIE: If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter. STEPHANIE: Or reach both of us at hosts@bikeshed.fm via email. JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week. ALL: Byeeeeeeee!!!!!!! AD: Did you know thoughtbot has a referral program? If you introduce us to someone looking for a design or development partner, we will compensate you if they decide to work with us. More info on our website at: tbot.io/referral. Or you can email us at referrals@thoughtbot.com with any questions.

Joël shares a unique, time-specific bug he encountered, which causes a page to crash only in January. This bug has been fixed in previous years, only to reemerge due to subsequent changes. Stephanie talks about her efforts to bring more structure to her work-from-home environment. She describes how setting up a bird feeder near her desk and keeping chocolates at her desk serve as incentives to work more from her desk. Together, Stephanie and Joël take a deep dive into the challenges of breaking down software development tasks into smaller, more manageable chunks. They explore the concept of 'vertical slice' development, where features are implemented in thin, fully functional segments, contrasting it with the more traditional 'horizontal slice' approach. This discussion leads to insights on collaborative work, the importance of iterative development, and strategies for efficient and effective software engineering. thoughtbot Live Streams (https://www.youtube.com/@thoughtbot/streams?themeRefresh=1) Stephanie’s Live Stream (https://www.youtube.com/watch?v=jWmCOMbOxTs) Joël’s Talk on Time (https://www.youtube.com/watch?v=54Hs2E7zsQg) Finish the Owl Meme (https://knowyourmeme.com/photos/572078-how-to-draw-an-owl) Full Stack Slices (https://thoughtbot.com/blog/break-apart-your-features-into-full-stack-slices) Elephant Carpaccio (https://blog.crisp.se/2013/07/25/henrikkniberg/elephant-carpaccio-facilitation-guide) Outside-in Feature Development (https://thoughtbot.com/blog/testing-from-the-outsidein) Working Iteratively (https://thoughtbot.com/blog/working-iteratively) Transcript:  STEPHANIE: Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Stephanie Minn. JOËL: And I'm Joël Quenneville. And together, we're here to share a bit of what we've learned along the way. STEPHANIE: So, Joël, what's new in your world in the year 2024? JOËL: Yeah, it's 2024. New year, new me. Or, in this case, maybe new year, new bugs? I'm working on a project where I ran into a really interesting time-specific bug. This particular page on the site only crashes in the month of January. There's some date logic that has a weird boundary condition there, and if you load that page during the month of January, it will crash, but during the entire rest of the year, it's fine. STEPHANIE: That's a fun New Year's tradition for this project [laughs], fixing this bug [laughs] every year. JOËL: It's been interesting because I looked a little bit at the git history of this bug, and it looks like it's been fixed in past Januarys, but then the fix changes the behavior slightly, so people bring the behavior back correct during the rest of the year that also happens to reintroduce the bug in January, and now I'm back to fixing it in January. So, it is a little bit of a tradition. STEPHANIE: Yeah, that is really funny. I was also recently debugging something, and we were having some flakiness with a test that we wrote. And we were trying to figure out because we had some date/time logic as well. And we were like, is there anything strange about this current time period that we are in that would potentially, you know, lead to a flaky test? And we were looking at the clock and we're like, "I don't think it's like, you know, midnight UTC or anything [laughs] like that." But, I mean, I don't know. It's like, how could you possibly think of, like, all of the various weird edge cases, you know, related to that kind of thing? I don't think I would ever be like, huh, it's January, so, surely, that must [laughs] mean that that's this particular edge case I'm seeing. JOËL: It's interesting because I feel like there's a couple of types of time-specific bugs that we see pretty frequently. If you're near the daylight savings boundary, let's say a week before sometimes, or whatever you're...if you're doing, like, a week from now logic or something like that, typically, I'll see failures in the test suite or maybe actual crashes in the code a week before springing forward and a week before falling back. And then, like you said, sometimes you see failures at the end of the day, Eastern time for me, when you approach that midnight UTC time boundary. I think this is the first time I've seen a failure in January due to the month being, like, a month boundary...or it's a year boundary really is what's happening. STEPHANIE: Yeah. That just sounds like another [laughs] thing you have to look out for. I'm curious: are you going to fix this bug for real or leave it for [laughs] 2025? JOËL: I've got a fix that I think is for real and that, like, not only fixes the break in January but also during the rest of the year gives the desired behavior. I think part of what's really interesting about this bug is that there are some subtle behavioral changes between a few different use cases where this code is called, part of which depend on when in the year you're calling it and whether you want to see it for today's date versus you can also specify a date that you want to see this report. And so, it turns out that there are a lot more edge cases than might be initially obvious. So, this turned into effectively a product discussion, and realizing, wait a minute, the code isn't telling the full story. There's more at a product level we need to discuss. And actually, I think I learned a lot about the product there. So, while it was maybe a surprising and kind of humorous bug to come across, I think it was actually a really good experience. STEPHANIE: Nice. That's awesome. That's a pretty good way to start the year, I would say. JOËL: I'd say so. How about you? What's new in your world? STEPHANIE: So, I don't know, I think towards the end of the year, last year, I was in a bit of a slump where I was in that work-from-couch phase of [laughs] the year, you know, like, things are slowing down and I, you know, winter was starting here. I wanted to be cozy, so I'd, you know, set up on the couch with a blanket. And I realized that I really wasn't sitting at my desk at all, and I kind of wanted to bring a little bit of that structure back into my workday, so I [chuckles] added some incentives for me to sit at my desk, which include I recently got a bird feeder that attaches to the window in my office. So, when I sit at my desk, I can hopefully see some birds hanging out. They are very flighty, so I've only seen birds when I'm, like, in the other room. And I'm like, oh, like, there's a bird at the bird feeder. Like, let me get up close to, like, get to admire them. And then as soon as I, like [laughs], get up close to the window, they fly away. So, I'm hoping that if I sit at my desk more, I'll spontaneously see more birds, and maybe they'll get used to, like, a presence closer to the window. And then my second incentive is I now have little chocolates at my desk [laughs]. JOËL: Nice. STEPHANIE: I've just been enjoying, like, a little treat and trying to keep them as a...okay, I've worked at my desk for an hour, and now I get a little reward for that [laughs]. JOËL: I like that. Do you know what kind of species of birds have been coming to your feeder? STEPHANIE: Ooh, yes. So, we got this birdseed mix called Cardinal and Friends [laughs]. JOËL: I love that. STEPHANIE: So, I have seen, like, a really beautiful red male cardinal come by. We get some robins and some chickadees, I think. Part of what I'm excited for this winter is to learn more how to identify more bird species. And I usually like to be out in nature and stuff, and winter is a hard time to do that. So, this is kind of my way of [chuckles] bringing that more into my life during the season. So, this is our first episode after a little bit of a break for the holidays. There actually has been some content of ours that has been published out in the world on the internet [laughs] during this time. And just wanted to point out in the few weeks that there weren't any Bike Shed episodes, I ended up doing a thoughtbot Rails development livestream with thoughtbot CEO Chad Pytel, and that was my first-time live streaming code [laughs]. And it was a really cool experience. I'm glad I had this podcast experience. So, I'm like, okay, well I have, you know, that, like, ability to do stuff kind of off script and present in the moment. But yeah, that was a really cool thing that I got to do, and I feel a little bit more confident about doing those kinds in the future. JOËL: And for those who are not aware, Chad does–I think it's a weekly live stream on Fridays where he's doing various types of code. So, he's done some work on some internal projects. He did a series where he upgraded, I think, a Rails 2 app all the way to Rails 7, typically with a guest who's another teammate from thoughtbot working on a thing. So, for those of our listeners that might find interesting, we'll put a link in the show notes where you can go see that. I think it's on YouTube and on Twitch. STEPHANIE: Yes. JOËL: What did you pair on? What kind of project were you doing for the livestream? STEPHANIE: So, we were working on thoughtbot's internal application called Hub, which is where we have, like, our internal messaging features. It's where we do a lot of our business operations-y things [laughs]. So, all of the, like, agency work that we do, we use our in-house software for that, and so Chad and I were working on a feature to introduce something that would help out with how we staff team members on projects. In other content news [laughs], Joël, I think you have something to share as well. JOËL: Yeah. So, we've mentioned on past episodes that I gave a talk at RubyConf this past November all about what the concept of time actually means within a program and the different ways of representing it, and the fact that time isn't really a single thing but actually kind of multiple related quantities. And over the holiday break, the talks from that conference got published. I'm pretty excited that that is now out there. We'd mentioned that as a highlight in the previous episode, highlighting accomplishments for the year, but it just wasn't quite out yet. We couldn't link it there. So, I'll leave a link in the show notes for this episode for anyone who's interested in seeing that. STEPHANIE: Sounds like that talk is also timely for a debug you -- JOËL: Ha ha ha! STEPHANIE: Were also mentioning earlier in the episode. So, a few episodes ago, I believe we mentioned that we had recently had, like, our company internal hackathon type thing where we have two days to get together and work with team members who we might not normally work with and get some cool projects started or do some team bonding, that kind of thing. And since I'm still, you know, unbooked on client work, I've been doing a lot of internal thoughtbot stuff, like continuing to work on the Hub app I mentioned just a bit ago. And from the hackathon, there was some work that was unfinished by, like, a project team that I decided to pick up this week as part of my internal work. And as I was kind of trying to gauge how much progress was made and, like, what was left to accomplish to get it over the finish line so it could be shipped, I noticed that because there were a couple of different people working on it, they had broken up this feature which was basically introducing, like, a new report for one of our teams to get some data on how certain projects are going. And there was, like, a UI portion and then some back-end portion, and then part of the back-end portion also involved a bit of a complex query that was pulled out as a separate ticket on its own. And so, all of those things were slightly, you know, were mostly done but just needed those, like, finishing touches, and then it also needed to come together. And I ended up pairing on this with another thoughtboter, and we spent the same amount of time that the hackathon was, so two days. We spent those two days on that, like, aspect of putting it all together. And I think I was a bit surprised by how much work that was, you know, we had kind of assumed that like, oh, like, all these pieces are mostly finished, but then the bulk of what we spended our time doing was integrating the components together. JOËL: Does this feel like a bit of a finish the rest of the OWL meme? STEPHANIE: What is that meme? I'm not familiar with it, but now I really want to know [laughs]. JOËL: It's a meme kind of making fun of some of these drawing tutorials where they're like, oh; first you draw, like, three circles. STEPHANIE: [laughs] JOËL: And then just finish the rest of the owl. STEPHANIE: [laughs] JOËL: And I was thinking of this beautifully drawn picture. STEPHANIE: Oh, that's so funny. Okay, yeah, I can see it in my head [laughs] now. It's like how to go from three circles, you know, to a recognizable [laughs] owl animal. JOËL: So, especially, they're like, oh, you know, like, we put in all the core classes and everything. It's all just basically there. You just need to connect it all together, and it's basically done [laughs]. And then you spend a lot of time actually getting that what feels like maybe the last 20 or 10% but takes maybe 80% of the time. STEPHANIE: Yeah, that sounds about right. So, you know, kind of working on that got me thinking about the alternative, which is honestly something that I'm still working on getting better at doing in my day-to-day. But there is this idea of a vertical slice or a full-stack slice, and that, basically, involves splitting a large feature into those full-stack slices. So, you have, like, a fully implemented piece rather than breaking them apart by layers of the stack. So, you know, I just see pretty frequently that, like, maybe you'll have a back-end ticket to do the database migration, to create your models, just whatever, maybe your controllers, or maybe that is even, like, another piece and then, like, the UI component. And those are worked on separately, maybe even by different people. But this vertical slice theory talks about how what you really want is to have a very thin piece of the feature that still delivers value but fully works. JOËL: As opposed to what you might call a horizontal slice, which would be something like, oh, I've built three Rails models. They're there. They're in the code. They talk to tables in the database, but there's nothing else happening with them. So, you've done work, but it's also more or less dead code. STEPHANIE: Yeah, that's a good point. I have definitely seen a lot of unused code paths [laughs] when you kind of go about it that way and maybe, like, that UI ticket never gets completed. JOËL: What are some tips for trying to do some of these narrower slices? Like, I have a ticket, and I have some work I need to do. And I want to break it down because I know it's going to be too big, and maybe the, like, intuitive way to do it is to split it by layers of your stack where I might do all the models, commit, ship that, deploy, then do some controllers, then do some view, or something like that, and you're suggesting instead going full stack. How do you break down the ticket more when all the pieces are interrelated? STEPHANIE: Yeah, that's a great point. One easy way to visualize it, especially if you have designs or something for this feature, right? Oftentimes, you can start to parse out sections or components of the user interface to be shipped separately. Like, yes, you would want all of it to have that rich feature, but if it's a view of some cards or something, and then, yeah, there's, like, the you can filter by them. You can search by them. All of those bits can be broken up to be like, well, like, the very basic thing that a customer would want to see is just that list of cards, and you can start there. JOËL: So, aggressively breaking down the card at, like, almost a product level. Instead of breaking it down by technical pieces, say, like, can we get even smaller amounts of behavior while still delivering value? STEPHANIE: Yeah, yeah, exactly. I like that you said product level because I think another axis of that could also be complexity. So, oftentimes, you know, I'll get a feature, and we're like, oh, we want to support these X number of things that we've identified [laughs]. You know, if it's like an e-com app you're building, you know, you're like, "Do we have all these products that we want to make sure to support?" And, you know, one way to break that down into that vertical slice is to ask, like, what if we started with just supporting one before we add variants or something like that? Teasing out, like, what would end up being the added complexity as you're developing, once you have to start considering multiple parameters, I think that is a good way to be able to start working more iteratively. And so, you don't have to hold all of that complexity in your head. JOËL: It's almost a bit of like a YAGNI principle but applied to features rather than to code. STEPHANIE: Yeah. Yeah. I like that. At first, I hesitated a little bit because I've certainly been in the position where someone has said like, "Well, we do really need this [laughs]." JOËL: Uh-huh. And, sometimes, the answer is, yes, we do need that, but what if I gave you a smaller version of that today, and we can do the other thing tomorrow? STEPHANIE: Right. Yeah, it's not like you're rejecting the idea that it's necessary but the way that you get about to that end result, right? JOËL: So, you keep using the term vertical slice or full-stack slice. I think when I hear that term, I think of specifically an article written by former thoughtboter, German Velasco, on our blog. But I don't know if that's maybe a term that has broader use in the industry. Is that a term that you've heard elsewhere? STEPHANIE: That's a good question. I think I mostly hear, you know, some form of like, "Can we break this ticket down further?" and not necessarily, like, if you think about how, right? I'm, like, kind of doing a motion with my hand [chuckles] of, like, slicing from top to bottom as opposed to, you know, horizontal. Yeah, I think that it may not be as common as I wish it were. Even if there's still some amount of adapting or, like, persuading your team members to get on board with this idea, like, I would be interested in, like, introducing that concept or that vocabulary to get teams talking about, like, how do they break down tickets? You know, like, what are they considering? Like, what alternatives are there? Like, are horizontal slices working for them or not? JOËL: A term that I've heard floating around and I haven't really pinned down is Elephant Carpaccio. Have you heard that before? STEPHANIE: I have, only because I, like, discovered a, like, workshop facilitation guide to run an exercise that is basically, like, helping people learn how to identify, like, smaller and smaller full-stack slices. But with the Elephant Carpaccio analogy, it's kind of like you're imagining a feature as big as an elephant. And you can create, like, a really thin slice out of them, and you can have infinite number of slices, but they still end up creating this elephant. And I guess you still get the value of [chuckles] a little carpaccio, a delicious [laughs] appetizer of thinly sliced meat. JOËL: I love a colorful metaphor. So, I'm curious: in your own practice, do you have any sort of guidelines or even heuristics that you like to use to help work in a more, I guess, iterative fashion by working with these smaller slices? STEPHANIE: Yeah, one thought that I had about it is that it plays really well with Outside-In Test Driven Development. JOËL: Hmmm. STEPHANIE: Yeah. So, if, you know, you are starting with a feature test, you have to start somewhere and, you know, maybe starting with, like, the most valuable piece of the feature, right? And you are starting at that level of user interaction if you're using Capybara, for example. And then it kind of forces you to drop down deeper into those layers. But once you go through that whole process of outside-in and then you arrive back to the top, you've created your full-stack feature [laughs], and that is shippable or, like, committable and, you know, potentially even shippable in and of itself. And you already have full test coverage with it. And that was a cool way that I saw some of those two concepts work well together. JOËL: Yeah, there is something really fun about the sort of Red-Green-Refactor cycle that TDD forces on you and that you're typically writing the minimum code required to pass a test. And it really forces you out of that developer brain where you're just like, oh, I've got to cover my edge cases. I've got to engineer for some things. And then maybe you realize you've written code that wasn't necessary. And so, I've found that often when I do, like, actually TDD a feature, I end up with code that's a lot leaner than I would otherwise. STEPHANIE: Yes, lean like a thin slice of Elephant Carpaccio. [laughter] JOËL: One thing you did mention that I wanted to highlight was the fact that when you do this outside-in approach for your tiny slice, at the end, it is shippable. And I think that is a core sort of tenet of this idea is that even though you're breaking things down into smaller and smaller slices, every slice is shippable to production. Like, it doesn't break the build. It doesn't break the website. And it provides some kind of value to the user. STEPHANIE: Yeah, absolutely. I think one thing that I still kind of get hung up on sometimes, and I'm trying to, you know, revisit this assumption is that idea of, like, is this too small? Like, is this valuable enough? When I mentioned earlier that I was working on a report, I think there was a part of me that's like, could I just ship a report with two columns [laughs]? And the answer is yes, right? Like, I thought about it, and I was like, well, if that data is, like, not available anywhere else, then, yeah, like, that would be valuable to just get out there. But I think the idea that, like, you know, originally, the hope was to have all of these things, these pieces of information, you know, available through this report, I think that, like, held me back a little bit from wanting to break it down. And I held it a little bit too closely and to be like, well, I really want to, like, you know, deliver something impressive. When you click on it, it's like, wow, like, look at all this data [laughs]. So, I'm trying to push back a little bit on my own preconceived notions that, like, there is such a thing as, like, a too small of a demo. JOËL: I've often worked with this at a commit level, trying to see, like, how small can I get a commit, and what is too small? And now you get into sort of the fraught question of what is a, you know, atomic commit? And I think, for me, where I've sort of come down is that a commit must pass CI. Like, I don't want a commit that's going to go into the main branch. I'm totally pro-work-in-progress commits on a branch; that's fine. But if it's going to get shipped into the main branch, it needs to be green. And it also cannot introduce dead code. STEPHANIE: Ooh. JOËL: So, if you're getting to the point where you're breaking either of those, you've got some sort of, like, partial commit that's maybe too small that needs more to be functional. Or you maybe need to restructure to say, look, instead of adding just ten models, can I add one model but also a little bit of a controller and a view? And now I've got a vertical slice. STEPHANIE: Yeah, which might even be less code [laughs] in the end. JOËL: Yes, it might be less code. STEPHANIE: I really like that heuristic of not introducing dead code, that being a goal. I'm going to think about that a lot [laughs] and try to start introducing that into when I think something is ready. JOËL: Another thing that I'll often do, I guess, that's almost like it doesn't quite fit in the slice metaphor, but it's trying to separate out any kind of refactor work into its own commit that is, you know, still follows those rules: it does not introduce dead code; it does not break the build; it's independently shippable. But that might be something that I do that sets me up for success when I want to do that next slice. So, maybe I'm trying to add a new feature, but just the way we built some of the internal models, they don't have the interface that I need right now, and that's fine because I don't want to build these models in anticipation of the future. I can change them in the future if I need. But now the future has come, and I need a slightly different shape. So, I start by refactoring, commit, maybe even ship that deploy. Maybe I then do my small feature afterwards. Maybe I come back next week and do the small feature, but there are two independent things, two different commits, maybe two different deploys. I don't know that I would call that refactor a slice and that it maybe goes across the full stack; maybe it doesn't. It doesn't show to the user because a refactor, by definition, is just changing the implementation without changing behavior. But I do like to break that out and keep it separate. And I guess it helps keep my slices lean, but I'm not quite sure where refactors fit into this metaphor. STEPHANIE: Yeah, that's interesting because, in my head, as I was listening to you talk about that, I was visualizing the owl again, the [laughs] owl meme. And I'm imagining, like, the refactoring making the slice richer, right? It's like you're adding details, and you're...it's like when you end up with the full animal, or the owl, the elephant, whatever, it's not just, like, a shoddy-looking drawing [laughs]. Like, ideally, you know, it has those details. Maybe it has some feathers. It's shaded in, and it is very fleshed out. That's just my weird, little brain trying [laughs] to stretch this metaphor to make it work. Another thing that I want to kind of touch a little bit more about when we're talking about how a lot of the work I was spending recently was that glue work, you know, the putting the pieces together, I think there was some aspect of discovery involved that was missed the first time around when these tickets were broken up more horizontally. I think that one really important piece that I was doing was trying to reconcile the different mental models that each person had when they were working on their separate piece. And so, maybe there's, like, an API, and then the frontend is expecting some sort of data, and, you know, you communicate it in a way that's, like, kind of hand-off-esque. And then when you put it together, it turns out that, oh, the pieces don't quite fit together, and how do you actually decide, like, what that mental model should be? Naming, especially, too, I've, you know, seen so many times when the name...like, an attribute on the frontend is named a little bit different than whatever is on the backend, and it takes a lot of work to unify that, like, to make that decision about, should they be the same? Should they be different? A lot of thought goes into putting those pieces together. And I think the benefit of a full-stack slice is that that work doesn't get lost. Especially if you are doing stuff like estimating, you're kind of discovering that earlier on. And I think what I just talked about, honestly, is what prevents those features from getting shipped in the end if you were working in a more horizontal way. JOËL: Yeah. It's so easy to have, like, big chunks of work in progress forever and never actually shipping. And one of the benefits of these narrower slices is that you're shipping more frequently. And that's, you know, interesting from a coding perspective, but it's kind of an agile methodology thing as well, the, like, ship smaller chunks more frequently. Even though you're maybe taking a little bit more overhead because you're having to, like, take the time to break down tasks, it will make your project move faster as a whole. An aspect that's really interesting to me, though, is what you highlighted about collaboration and the fact that every teammate has a slightly different mental model. And I think if you take the full-stack slice and every member is able to use their mental model, and then close the loop and actually, like, do a complete thing and ship it, I think it allows every other member who's going to have a slightly different mental model of the problem to kind of, yes, and... the other person rather than all sort of independently doing their things and having to reconcile them at the end. STEPHANIE: Yeah, I agree. I think I find, you know, a lot of work broken out into backend and frontend frequently because team members might have different specialties or different preferences about where they would like to be working. But that could also be, like, a really awesome opportunity for pairing [laughs]. Like, if you have someone who's more comfortable in the backend or someone more comfortable in the frontend to work on that full-stack piece together, like, even outside of the in-the-weeds coding aspects of it, it's like you're, at the very least, making sure that those two folks have that same mental model. Or I like what you said about yes, and... because it gets further refined when you have people who are maybe more familiar with, like, something about the app, and they're like, "Oh, like, don't forget about we should consider this." I think that, like, diversity of experience, too, ends up being really valuable in getting that abstraction to be more accurate so that it best represents what you're trying to build. JOËL: Early on, when I was pretty new working at thoughtbot, somebody else at the company had given me the advice that if I wanted to be more effective and work faster on projects, I needed to start breaking my work down into smaller chunks, and this is, you know, fairly junior developer at the time. The advice sounds solid, and everything we've talked about today sounds really solid. Doing it in practice is hard, and it's taken me, you know, a decade, and I'm still working on getting better at it. And I wrote an article about working iteratively that covers a lot of different elements where I've kind of pulled on threads and found out ways where you can get better at this. But I do want to acknowledge that this is not something that's easy and that just like the code that we're working on iteratively, our technique for breaking things down is something that we improve on iteratively. And it's a journey we're all on together. STEPHANIE: I'm really glad that you brought up how hard it is because as I was thinking about this topic, I was considering barriers into working in that vertical slice way, and barriers that I personally experience, as well as just I have seen on other teams. I had alluded to some earlier about, like, the perception of if I ship this small thing, is it impressive enough, or is it valuable enough? And I think I realized that, like, I was getting caught up in, like, the perception part, right? And maybe it doesn't matter [chuckles], and I just need to kind of shift the way I'm thinking about it. And then, there are more real barriers or, like, concrete barriers that are tough. Long feedback loops is one that I've encountered on a team where it's just really hard to ship frequently because PR reviews aren't happening fast enough or your CI or deployment process is just so long that you're like, I want to stuff everything into [chuckles] this one PR so that at least I won't have to sit and wait [laughs]. And that can be really hard to work against, but it could also be a really interesting signal about whether your processes are working for you. It could be an opportunity to be like, "I would like to work this way, but here are the things that are preventing me from really embracing it. And is there any improvement I can make in those areas?" JOËL: Yeah. There's a bit of a, like, vicious cycle that happens there sometimes, especially around PR review, where when it takes a long time to get reviews, you tend to decide, well, I'm going to not make a bunch of PRs; I'm going to make one big one. But then big PRs are very, like, time intensive and require you to commit a lot of, like, focus and energy to them, which means that when you ask me for a review, I'm going to wait longer before I review it, which is going to incentivize you to build bigger PRs, which is going to incentivize me to wait longer, and now we just...it's a vicious cycle. So, I know I've definitely been on projects where a question the team has had is, "How can we improve our process? We want faster code review." And there's some aspect of that that's like, look, everybody just needs to be more disciplined or more alert and try to review things more frequently. But there's also an element of if you do make things smaller, you make it much easier for people to review your code in between other things. STEPHANIE: Yeah, I really liked you mentioning incentives because I think that could be a really good place to start if you or your team are interested in making a change like this, you know, making an effort to look at your team processes and being like, what is incentivized here, and what does our system encourage or discourage? And if you want to be making that shift, like, that could be a good place to start in identifying places for improvement. JOËL: And that happens on a broader system level as well. If you look at what does it take to go from a problem that is going to turn into a ticket to in-production in front of a client, how long is that loop? How complex are the steps to get there? The longer that loop is, the slower you're iterating. And the easier it is for things to just get hung up or for you to waste time, the harder it is for you to change course. And so, oftentimes, I've come on to projects with clients and sort of seen something like that, and sort of seen other pain points that the team has and sort of found that one of the root causes is saying, "Look, we need to tighten that feedback loop, and that's going to improve all these other things that are kind of constellation around it." STEPHANIE: Agreed. On that note, shall we wrap up? JOËL: Let's wrap up. STEPHANIE: Show notes for this episode can be found at bikeshed.fm. JOËL: This show has been produced and edited by Mandy Moore. STEPHANIE: If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter. STEPHANIE: Or reach both of us at hosts@bikeshed.fm via email. JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week. ALL: Byeeeeeeee!!!!!!! AD: Did you know thoughtbot has a referral program? If you introduce us to someone looking for a design or development partner, we will compensate you if they decide to work with us. More info on our website at: tbot.io/referral. Or you can email us at referrals@thoughtbot.com with any questions.

Stephanie is hosting a holiday cookie swap. Joël talks about participating in thoughtbot's end-of-the-year hackathon, Ralphapalooza. We had a great year on the show! The hosts wrap up the year and discuss their favorite episodes, the articles, books, and blog posts they’ve read and loved, and other highlights of 2023 (projects, conferences, etc). Olive Oil Sugar Cookies With Pistachios & Lemon Glaze (https://food52.com/recipes/82228-olive-oil-sugar-cookies-recipe-with-pistachios-lemon) thoughtbot’s Blog (https://thoughtbot.com/blog) Episode 398: Developing Heuristics For Writing Software (https://www.bikeshed.fm/398) Episode 374: Discrete Math (https://www.bikeshed.fm/374) Episode 405: Sandi Metz’s Rules (https://www.bikeshed.fm/405) Episode 391: Learn with APPL (https://www.bikeshed.fm/391) Engineering Management for the Rest of Us (https://www.engmanagement.dev/) Confident Ruby (https://pragprog.com/titles/agcr/confident-ruby/) Working with Maybe from Elm Europe (https://www.youtube.com/watch?v=43eM4kNbb6c) Sustainable Rails Book (https://sustainable-rails.com/) Episode 368: Sustainable Web Development (https://www.bikeshed.fm/368) Domain Modeling Made Functional (https://pragprog.com/titles/swdddf/domain-modeling-made-functional/) Simplifying Tests by Extracting Side Effects (https://thoughtbot.com/blog/simplify-tests-by-extracting-side-effects) The Math Every Programmer Needs (https://www.youtube.com/watch?v=wzYYT40T8G8) Mermaid.js sequence diagrams (https://mermaid.js.org/syntax/sequenc) Sense of Belonging and Software Teams (https://www.drcathicks.com/post/sense-of-belonging-and-software-teams) Preemptive Pluralization is (Probably) Not Evil (https://www.swyx.io/preemptive-pluralization) Digging through the ashes (https://everythingchanges.us/blog/digging-through-the-ashes/) Transcript: JOËL: Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Joël Quenneville. STEPHANIE: And I'm Stephanie Minn. And together, we're here to share a bit of what we've learned along the way. JOËL: So, Stephanie, what's new in your world? STEPHANIE: I am so excited to talk about this. I'm, like, literally smiling [chuckles] because I'm so pumped. Sometimes, you know, we get on to record, and I'm like, oh, I got to think of something that's new, like, my life is so boring. I have nothing to share. But today, I am excited to tell you about [chuckles] the holiday cookie swap that I'm hosting this Sunday [laughs] that I haven't been able to stop thinking about or just thinking about all the cookies that I'm going to get to eat. It's going to be my first time throwing this kind of shindig, and I'm so pleased with myself because it's such a great idea. You know, it's like, you get to share cookies, and you get to have all different types of cookies, and then people get to take them home. And I get to see all my friends. And I'm really [chuckles] looking forward to it. JOËL: I don't think I've ever been to a cookie swap event. How does that work? Everybody shows up with cookies, and then you leave with what you want? STEPHANIE: That's kind of the plan. I think it's not really a...there's no rules [laughs]. You can make it whatever you want it to be. But I'm asking everyone to bring, like, two dozen cookies. And, you know, I'm hoping for a lot of fun variety. Myself I'm planning on making these pistachio olive oil cookies with a lemon glaze and also, maybe, like, a chewy ginger cookie. I haven't decided if I'm going to go so extra to make two types, but we'll see. And yeah, we'll, you know, probably have some drinks and be playing Christmas music, and yeah, we'll just hang out. And I'm hoping that everyone can kind of, like, take home a little goodie bag of cookies as well because I don't think we'll be going through all of them. JOËL: Hearing you talk about this gave me an absolutely terrible idea. STEPHANIE: Terrible or terribly awesome? [laughs] JOËL: So, imagine you have the equivalent of, let's say, a LAN party. You all show up with your laptops. STEPHANIE: [laughs] JOËL: You're on a network, and then you swap browser cookies randomly. STEPHANIE: [laughs] Oh no. That would be really funny. That's a developer's take on a cookie party [laughs] if I've ever heard one. JOËL: Slightly terrifying. Now I'm just browsing, and all of a sudden, I guess I'm logged into your Facebook or something. Maybe you only swap the tracking cookies. So, I'm not actually logged into your Facebook, but I just get to see the different ad networks it would typically show you, and you would see my ads. That's maybe kind of fun or maybe terrifying, depending on what kind of ads you normally see. STEPHANIE: That's really funny. I'm thinking about how it would just be probably very misleading and confusing for those [laughs] analytics spenders, but that's totally fine, too. Might I suggest also having real cookies to munch on as well while you are enjoying [laughs] this browser cookie-swapping party? JOËL: I 100% agree. STEPHANIE: [laughs] JOËL: I'm curious: where do you stand on raisins in oatmeal cookies? STEPHANIE: Ooh. JOËL: This is a divisive question. STEPHANIE: They're fine. I'll let other people eat them. And occasionally, I will also eat an oatmeal cookie with raisins, but I much prefer if the raisins are chocolate chips [chuckles]. JOËL: That is the correct answer. STEPHANIE: [laughs] Thank you. You know, I understand that people like them. They're not for me [laughs]. JOËL: It's okay. Fans can send us hate mail about why we're wrong about oatmeal cookies. STEPHANIE: Yeah, honestly, that's something that I'm okay with being wrong about on the internet [laughs]. So, Joël, what's new in your world? JOËL: So, as of this recording, we've just recently done thoughtbot's end-of-the-year hackathon, what we call Ralphapalooza. And this is sort of a time where you kind of get to do pretty much any sort of company or programming-related activity that you want as long as...you have to pitch it and get at least two other colleagues to join you on the project, and then you've got two days to work on it. And then you can share back to the team what you've done. I was on a project where we were trying to write a lot of blog posts for the thoughtbot blog. And so, we're just kind of getting together and pitching ideas, reviewing each other's articles, writing things at a pretty intense rate for a couple of days, trying to flood the blog with articles for the next few weeks. So, if you're following the blog and as the time this episode gets released, you're like, "Wow, there's been a lot of articles from the thoughtbot blog recently," that's why. STEPHANIE: Yes, that's awesome. I love how much energy that the blog post-writing party garnered. Like, I was just kind of observing from afar, but it sounds like, you know, people who maybe had started posts, like, throughout the year had dedicated time and a good reason to revisit them, even if they had been, you know, kind of just, like, sitting in a draft for a while. And I think what also seemed really nice was people were just around to support, to review, and were able to make that a priority. And it was really cool to see all the blog posts that are queued up for December as a result. JOËL: People wrote some great stuff. So, I'm excited to see all of those come out. I think we've got pretty much a blog post every day coming out through almost the end of December. So, it's exciting to see that much content created. STEPHANIE: Yeah. If our listeners want more thoughtbot content, check out our blog. JOËL: So, as mentioned, we're recording this at the end of the year. And I thought it might be fun to do a bit of a retrospective on what this year has been like for you and I, Stephanie, both in terms of different work that we've done, the learnings we've had, but maybe also look back a little bit on 2023 for The Bike Shed and what that looked like. STEPHANIE: Yes. I really enjoyed thinking about my year and kind of just reveling and having been doing this podcast for over a year now. And yeah, I'm excited to look back a little bit on both things we have mentioned on the show before and things maybe we haven't. To start, I'm wondering if you want to talk a little bit about some of our favorite episodes. JOËL: Favorite episodes, yes. So, I've got a couple that are among my favorites. We did a lot of good episodes this year. I really liked them. But I really appreciated the episode we did on heuristics, that's Episode 398, where we got to talk a little bit about what goes into a good heuristic, how we tend to come up with them. A lot of those, like, guidelines and best practices that you hear people talk about in the software world and how to make your own but then also how to deal with the ones you hear from others in the software community. So, I think that was an episode that the idea, on the surface, seemed really basic, and then we went pretty deep with it. And that was really fun. I think a second one that I really enjoyed was also the one that I did with Sara Jackson as a guest, talking about discrete math and its relevance to the day-to-day work that we do. That's Episode 374. We just had a lot of fun with that. I think that's a topic that more developers, more web developers, would benefit from just getting a little bit more discrete math in their lives. And also, there's a clip in there where Sara reinterprets a classic marketing jingle with some discrete math terms in there instead. It was a lot of fun. So, we'd recommend people checking that one out. STEPHANIE: Nice. Yes. I also loved those episodes. The heuristics one was really great. I'm glad you mentioned it because one of my favorite episodes is kind of along a similar vein. It's one of the more recent ones that we did. It's Episode 405, where we did a bit of a retro on Sandi Metz' Rules For Developers. And those essentially are heuristics, right? And we got to kind of be like, hey, these are someone else's heuristics. How do we feel about them? Have we embodied them ourselves? Do we follow them? What parts do we take or leave? And I just remember having a really enjoyable conversation with you about that. You and I have kind of treated this podcast a little bit like our own two-person book club [laughs]. So, it felt a little bit like that, right? Where we were kind of responding to, you know, something that we both have read up on, or tried, or whatever. So, that was a good one. Another one of my favorite episodes was Episode 391: Learn with APPL [laughs], in which we basically developed our own learning framework, or actually, credit goes to former Bike Shed host, Steph Viccari, who came up with this fun, little acronym to talk about different things that we all kind of need in our work lives to be fulfilled. Our APPL stands for Adventure, Passion, Profit, and Low risk. And that one was really fun just because it was, like, the opposite of what I just described where we're not discussing someone else's work but discovered our own thing out of, you know, these conversations that we have on the show, conversations we have with our co-workers. And yeah, I'm trying to make it a thing, so I'm plugging it again [laughs]. JOËL: I did really like that episode. One, I think, you know, this APPL framework is a little bit playful, which makes it fun. But also, I think digging into it really gives some insight on the different aspects that are relevant when planning out further growth or where you want to invest your sort of professional development time. And so, breaking down those four elements led to some really insightful conversation around where do I want to invest time learning in the next year? STEPHANIE: Yeah, absolutely. JOËL: By the way, we're mentioning a bunch of our favorite things, some past episodes, and we'll be talking about a lot of other types of resources. We will be linking all of these in the show notes. So, for any of our listeners who are like, "Oh, I wonder what is that thing they mentioned," there's going to be a giant list that you can check out. STEPHANIE: Yeah. I love whenever we are able to put out an episode with a long list of things [laughs]. JOËL: It's one of the fun things that we get to do is like, oh yeah, we referenced all these things. And there is this sort of, like, further reading, more threads to pull on for people who might be interested. So, you'd mentioned, Stephanie, that, you know, sometimes we kind of treat this as our own little mini, like, two-person book club. I know that you're a voracious reader, and you've mentioned so many books over the course of the year. Do you have maybe one or two books that have been kind of your favorites or that have stood out to you over 2023? STEPHANIE: I do. I went back through my reading list in preparation for this episode and wanted to call out the couple of books that I finished. And I think I have, you know, I mentioned I was reading them along the way. But now I get to kind of see how having read them influenced my work life this past year, which is pretty cool. So, one of them is Engineering Management for the Rest of Us by Sarah Drasner. And that's actually one that really stuck with me, even though I'm not a manager; I don't have any plans to become a manager. But one thing that she talks about early on is this idea of having a shared value system. And you can have that at the company level, right? You have your kind of corporate values. You can have that at the team level with this smaller group of people that you get to know better and kind of form relationships with. And then also, part of that is, like, knowing your individual values. And having alignment in all three of those tiers is really important in being a functioning and fulfilled team, I think. And that is something that I don't think was really spelled out very explicitly for me before, but it was helpful in framing, like, past work experiences, where maybe I, like, didn't have that alignment and now identify why. And it has helped me this year as I think about my client work, too, and kind of where I sit from that perspective and helps me realize like, oh, like, this is why I'm feeling this way, and this is why it's not quite working. And, like, what do I do about it now? So, I really enjoyed that. JOËL: Would you recommend this book to others who are maybe not considering a management path? STEPHANIE: Yeah. JOËL: So, even if you're staying in the IC track, at least for now, you think that's a really powerful book for other people. STEPHANIE: Yeah, I would say so. You know, maybe not, like, all of it, but there's definitely parts that, you know, she's writing for the rest of us, like, all of us maybe not necessarily natural born leaders who knew that that's kind of what we wanted. And so, I can see how people, you know, who are uncertain or maybe even, like, really clearly, like, "I don't think that's for me," being able to get something out of, like, either those lessons in leadership or just to feel a bit, like, validated [laughs] about the type of work that they aren't interested in. Another book that I want to plug real quick is Confident Ruby by Avdi Grimm. That one was one I referenced a lot this year, working with newer developers especially. And it actually provided a good heuristic [laughs] for me to talk about areas that we could improve code during code review. I think that wasn't really vocabulary that I'd used, you know, saying, like, "Hey, how confident is this code? How confident is this method and what it will receive and what it's returning?" And I remember, like, several conversations that I ended up having on my teams about, like, return types as a result and them having learned, like, a new way to view their code, and I thought that was really cool. JOËL: I mean, learning to deal with uncertainty and nil in Ruby or maybe even, like, error states is just such a core part of writing software. I feel like this is something that I almost wish everyone was sort of assigned maybe, like, a year into their programming career because, you know, I think the first year there's just so many things you've got to learn, right? Like basic programming and, like, all these things. But, like, you're looking maybe I can start going a little bit deeper into some topic. I think that some topic, like, pretty high up, would be building a mental model for how to deal with uncertainty because it's such a source of bugs. And Avdi Grimm's book, Confident Ruby, is...I would put that, yeah, definitely on a recommended reading list for everybody. STEPHANIE: Yeah, I agree. And I think that's why I found myself, you know, then recommending it to other people on my team and kind of having something I can point to. And that was really helpful in the kind of mentorship that I wanted to offer. JOËL: I did a deep dive into uncertainty and edge cases in programs several years back when I was getting into Elm. And I was giving a talk at Elm Europe about how Elm handles uncertainty, which is a little bit different than how Ruby does it. But a lot of the underlying concepts are very similar in terms of quarantining uncertainty and pushing it to the edges and things like that. Trying to write code that is more confident that is definitely a term that I used. And so Confident Ruby ended up being a little bit of an inspiration for my own journey there, and then, eventually, the talk that I gave that summarized my learnings there. STEPHANIE: Nice. Do you have any reading recommendations or books that stood out to you this year? JOËL: So, I've been reading two technical books kind of in tandem this year. I have not finished either of them, but I have been enjoying them. One is Sustainable Rails by David Bryant Copeland. We had an episode at the beginning of this year where we talked a little bit about our initial impressions from, I think, the first chapter of the book. But I really love that vocabulary of writing Ruby and Rails code, in particular, in a way that is sustainable for a team. And that premise, I think, just gives a really powerful mindset to approach structuring Rails apps. And the other book that I've been reading is Domain Modeling Made Functional, so kind of looking at some domain-driven design ideas. But most of the literature is typically written to an object-oriented audience, so taking a look at it from more of a functional programming perspective has been really interesting. And then I've been, weirdly enough, taking some of those ideas and translating back into the object-oriented world to apply to code I'm writing in Ruby. I think that has been a very useful exercise. STEPHANIE: That's awesome. And it's weird and cool how all those things end up converging, right? And exploring different paradigms really just lets you develop more insight into wherever you're working. JOËL: Sometimes the sort of conversion step that you have to do, that translation, can be a good tool for kind of solidifying learnings or better understanding. So, I'm doing this sort of deep learning thing where I'm taking notes as I go along. And those notes are typically around, what other concepts can I connect ideas in the book? So, I'll be reading and say, okay, on page 150, he mentioned this concept. This reminds me of this idea from TDD. I could see this applying in a different way in an object-oriented world. And interestingly, if you apply this, it sort of converges on maybe single responsibility or whatever other OO principle. And that's a really interesting connection. I always love it when you do see sort of two or three different angles converging together on the same idea. STEPHANIE: Yeah, absolutely. JOËL: I've written a blog post, I think, two years ago around how some theory from functional programming sort of OO best practices and then TDD all kind of converge on sort of the same approach to designing software. So, you can sort of go from either direction, and you kind of end in the same place or sort of end up rediscovering principles from the other two. We'll link that in the show notes. But that's something that I found was really exciting. It didn't directly come from this book because, again, I wrote this a couple of years ago. But it is always fun when you're exploring two or three different paradigms, and you find a convergence. It really deepens your understanding of what's happening. STEPHANIE: Yeah, absolutely. I like what you said about how this book is different because it is making that connection between things that maybe seem less related on the surface. Like you're saying, there's other literature written about how domain modeling and object-oriented programming make more sense a little bit more together. But it is that, like, bringing in of different schools of thought that can lead to a lot of really interesting discovery about those foundational concepts. JOËL: I feel like dabbling in other paradigms and in other languages has made me a better Ruby developer and a better OO programmer, a lot of the work I've done in Elm. This book that I'm reading is written in F#. And all these things I can kind of bring back, and I think, have made me a better Ruby developer. Have you had any experiences like that? STEPHANIE: Yeah. I think I've talked a little bit about it on the show before, but I can't exactly recall. There were times when my exploration in static typing ended up giving me that different mindset in terms of the next time I was coding in Ruby after being in TypeScript for a while, I was, like, thinking in types a lot more, and I think maybe swung a little bit towards, like, not wanting to metaprogram as much [laughs]. But I think that it was a useful, like you said, exercise sometimes, too, and just, like, doing that conversion or translating in your head to see more options available to you, and then deciding where to go from there. So, we've talked a bit about technical books that we've read. And now I kind of want to get into some in-person highlights for the year because you and I are both on the conference circuit and had some fun trips this year. JOËL: Yeah. So, I spoke at RailsConf this spring. I gave a talk on discrete math and how it is relevant in day-to-day work for developers, actually inspired by that Bike Shed episode that I mentioned earlier. So, that was kind of fun, turning a Bike Shed episode into a conference talk. And then just recently, I was at RubyConf in San Diego, and I gave a talk there around time. We often talk about time as a single quantity, but there's some subtle distinctions, so the difference between a moment in time versus a duration and some of the math that happens around that. And I gave a few sort of visual mental models to help people keep track of that. As of this recording, the talk is not out yet, so we're not going to be able to link to it. But if you're listening to this later in 2024, you can probably just Google RubyConf "Which Time Is It?" That's the name of the talk. And you'll be able to find it. STEPHANIE: Awesome. So, as someone who is giving talks and attending conferences every year, I'm wondering, was this year particularly different in any way? Was there something that you've, like, experienced or felt differently community-wise in 2023? JOËL: Conferences still feel a little bit smaller than they were pre-COVID. I think they are still bouncing back. But there's definitely an energy that's there that's nice to have on the conference scene. I don't know, have you experienced something similar? STEPHANIE: I think I know what you're talking about where, you know, there was that time when we weren't really meeting in person. And so, now we're still kind of riding that wave of, like, getting together again and being able to celebrate and have fun in that way. I, this year, got to speak at Blue Ridge Ruby in June. And that was a first-time regional conference. And so, that was, I think, something I had noticed, too, is the emergence of regional conferences as being more viable options after not having conferences for a few years. And as a regional conference, it was even smaller than the bigger national Ruby Central conferences. I really enjoyed the intimacy of that, where it was just a single track. So, everyone was watching talks together and then was on breaks together, so you could mingle. There was no FOMO of like, oh, like, I can't make this talk because I want to watch this other one. And that was kind of nice because I could, like, ask anyone, "What did you think of, like, X talk or like the one that we just kind of came out of and had that shared experience?" That was really great. And I got to go tubing for the first time [laughs] in Asheville. That's a memory, but I am still thinking about that as we get into winter. I'm like, oh yeah, the glorious days of summer [laughs] when I was getting to float down a lazy river. JOËL: Nice. I wasn't sure if this was floating down a lazy river on an inner tube or if this was someone takes you out on a lake with a speed boat, and you're getting pulled. STEPHANIE: [laughs] That's true. As a person who likes to relax [laughs], I definitely prefer that kind of tubing over a speed boat [laughs]. JOËL: What was the topic of your talk? STEPHANIE: So, I got to give my talk about nonviolent communication in pair programming for a second time. And that was also my first time giving a talk for a second time [laughs]. That was cool, too, because I got to revisit something and go deeper and kind of integrate even more experiences I had. I just kind of realized that even if you produce content once, like, there's always ways to deepen it or shape it a little better, kind of, you know, just continually improving it and as you learn more and as you get more experience and change. JOËL: Yeah. I've never given a talk twice, and now you've got me wondering if that's something I should do. Because making a bespoke talk for every conference is a lot of work, and it might be nice to be able to use it more than once. Especially I think for some of the regional conferences, there might be some value there in people who might not be able to go to a big national conference but would still like to see your talk live. Having a mix of maybe original content and then content that is sort of being reshared is probably a great combo for a regional conference. STEPHANIE: Yeah, definitely. That's actually a really good idea, yeah, to just be able to have more people see that content and access it. I like that a lot. And I think it could be really cool for you because we were just talking about all the ways that our mental models evolve the more stuff that we read and consume. And I think there's a lot of value there. One other conference that I went to this year that I just want to highlight because it was really cool that I got to do this: I went to RubyKaigi in Japan [laughs] back in the spring. And I had never gone to an international conference before, and now I'm itching to do more of that. So, it would be remiss not to mention it [laughs]. I'm definitely inspired to maybe check out some of the conferences outside of the U.S. in 2024. I think I had always been a little intimidated. I was like, oh, like, it's so far [laughs]. Do I really have, like, that good of a reason to make a trip out there? But being able to meet Rubyists from different countries and seeing how it's being used in other parts of the world, I think, made me realize that like, oh yeah, like, beyond my little bubble, there's so many cool things happening and people out there who, again, like, have that shared love of Ruby. And connecting with them was, yeah, just so new and something that I would want to do more of. So, another thing that we haven't yet gotten into is our actual work-work or our client work [laughs] that we do at thoughtbot for this year. Joël, I'm wondering, was there anything especially fun or anything that really stood out to you in terms of client work that you had to do this year? JOËL: So, two things come to mind that were novel for me. One is I did a Rails integration against Snowflake, the data warehouse, using an ODBC connection. We're not going through an API; we're going through this DB connection. And I never had to do that before. I also got to work with the new-ish Rails multi-database support, which actually worked quite nice. That was, I think, a great learning experience. Definitely ran into some weird edge cases, or some days, I was really frustrated. Some days, I was actually, like, digging into the source code of the C bindings of the ODBC gem. Those were not the best days. But definitely, I think, that kind of integration and then Snowflake as a technology was really interesting to explore. The other one that's been really interesting, I think, has been going much deeper into the single sign-on world. I've been doing an integration against a kind of enterprise SAML server that wants to initiate sign-in requests from their portal. And this is a bit of an alphabet soup, but the term here is IdP-initiated SSO. And so, I've been working with...it's a combination of this third-party kind of corporate SAML system, our application, which is a Rails app, and then Auth0 kind of sitting in the middle and getting all of them to talk to each other. There's a ridiculous number of redirects because we're talking SAML on one side and OIDC on the other and getting everything to line up correctly. But that's been a really fun, new set of things to learn. STEPHANIE: Yeah, that does sound complicated [laughs] just based on what you shared with me, but very cool. And I was excited to hear that you had had a good experience with the Rails multi-database part because that was another thing that I remember being...it had piqued my interest when it first came out. I hope I get to, you know, utilize that feature on a project soon because that sounds really fun. JOËL: One thing I've had to do for this SSO project is lean a lot on sequence diagrams, which are those diagrams that sort of show you, like, being redirected from different places, and, like, okay, server one talks to server two talks, to the browser. And so, when I've got so many different actors and sort of controllers being passed around everywhere, it's been hard to keep track of it in my head. And so, I've been doing a lot of these diagrams, both for myself to help understand it during development, and then also as documentation to share back with the team. And I found that Mermaid.js supports sequence diagrams as a diagram type. Long-term listeners of the show will know that I am a sucker for a good diagram. I love using Mermaid for a lot of things because it's supported. You can embed it in a lot of places, including in GitHub comments, pull requests. You can use it in various note systems like Notion or Obsidian. And you can also just generate your own on mermaid.live. And so, that's been really helpful to communicate with the rest of the team, like, "Hey, we've got this whole process where we've got 14 redirects across four different servers. Here's what it looks like. And here, like, we're getting a bug on, you know, redirect number 8 of 14. I wonder why," and then you can start a conversation around debugging that. STEPHANIE: Cool. I was just about to ask what tool you're using to generate your sequence diagrams. I didn't know that Mermaid supported them. So, that's really neat. JOËL: So, last year, when we kind of looked back over 2022, one thing that was really interesting that we did is we talked about what are articles that you find yourself linking to a lot that are just kind of things that maybe were on your mind or that were a big part of conversations that happened over the year? So, maybe for you, Stephanie, in 2023, what are one or two articles that you find yourself sort of constantly linking to other people? STEPHANIE: Yes. I'm excited you asked about this. One of them is an article by a person named Cat Hicks, who has a PhD in experimental psychology. She's a data scientist and social scientist. And lately, she's been doing a lot of research into the sense of belonging on software teams. And I think that's a theme that I am personally really interested in, and I think has kind of been something more people are talking about in the last few years. And she is kind of taking that maybe more squishy idea and getting numbers for it and getting statistics, and I think that's really cool. She points out belonging as, like, a different experience from just, like, happiness and fulfillment, and that really having an impact on how well a team is functioning. I got to share this with a few people who were, you know, just in that same boat of, like, trying to figure out, what are the behaviors kind of on my team that make me feel supported or not supported? And there were a lot of interesting discussions that came out of sharing this article and kind of talking about, especially in software, where we can be a little bit dogmatic. And we've kind of actually joked about it on the podcast [chuckles] before about, like, we TDD or don't TDD, or, you know, we use X tool, and that's just like what we have to do here. She writes a little bit about how that can end up, you know, not encouraging people offering, like, differing opinions and being able to feel like they have a say in kind of, like, the team's direction. And yeah, I just really enjoyed a different way of thinking about it. Joël, what about you? What are some articles you got bookmarked? [chuckles] JOËL: This year, I started using a bookmark manager, Raindrop.io. That's been nice because, for this episode, I could just look back on, what are some of my bookmarks this year? And be like, oh yeah, this is the thing that I have been using a lot. So, an article that I've been linking is an article called Preemptive Pluralization is (Probably) Not Evil. And it kind of talks a little bit about how going from code that works over a collection of two items to a collection of, you know, 20 items is very easy. But sometimes, going from one to two can be really challenging. And when are the times where you might want to preemptively make something more than one item? So, maybe using it has many association rather than it has one or making an attribute a collection rather than a single item. Controversial is not the word for it, but I think challenges a little bit of the way people typically like to write code. But across this year, I've run into multiple projects where they have been transitioning from one to many. That's been an interesting article to surface as part of those conversations. Whether your team wants to do this preemptively or whether they want to put it off and say in classic YAGNI (You Aren't Gonna Need It) form, "We'll make it single for now, and then we'll go plural," that's a conversation for your team. But I think this article is a great way to maybe frame the conversation. STEPHANIE: Cool. Yeah, I really like that almost, like, a counterpoint to YAGNI [laughs], which I don't think I've ever heard anyone say that out loud [laughs] before. But as soon as you said preemptive pluralization is not evil, I thought about all the times that I've had to, like, write code, text in which a thing, a variable could be either one or many [laughs] things. And I was like, ooh, maybe this will solve that problem for me [laughs]. JOËL: Speaking of pluralization, I'm sure you've been linking to more than just one article this year. Do you have another one that you find yourself coming up in conversations where you've always kind of like, "Hey, dropping this link," where it's almost like your thing? STEPHANIE: Yes. And that is basically everything written by Mandy Brown [laughs], who is a work coach that I actually started working with this year. And one of the articles that really inspired me or really has been a topic of conversation among my friends and co-workers is she has a blog post called Digging Through the Ashes. And it's kind of a meditation on, like, post burnout or, like, what's next, and how we have used this word as kind of a catch-all to describe, you know, this collective sense of being just really tired or demoralized or just, like, in need of a break. And what she offers in that post is kind of, like, some suggestions about, like, how can we be more specific here and really, you know, identify what it is that you're needing so that you can change how you engage with work? Because burnout can mean just that you are bored. It can mean that you are overworked. It can mean a lot of things for different people, right? And so, I definitely don't think I'm alone [laughs] in kind of having to realize that, like, oh, these are the ways that my work is or isn't changing and, like, where do I want to go next so that I might feel more sustainable? I know that's, like, a keyword that we talked about earlier, too. And that, on one hand, is both personal but also technical, right? It, like, informs the kinds of decisions that we make around our codebase and what we are optimizing for. And yeah, it is both technical and cultural. And it's been a big theme for me this year [laughs]. JOËL: Yeah. Would you say it's safe to say that sustainability would be, if you want to, like, put a single word on your theme for the year? Would that be a fair word to put there? STEPHANIE: Yeah, I think so. Definitely discovering what that means for me and helping other people discover what that means for them, too. JOËL: I feel like we kicked off the year 2023 by having that discussion of Sustainable Rails and how different technical practices can make the work there feel sustainable. So, I think that seems to have really carried through as a theme through the year for you. So, that's really cool to have seen that. And I'm sure listeners throughout the year have heard you mention these different books and articles. Maybe you've also been able to pick up a little bit on that. So, I'm glad that we do this show because you get a little bit of, like, all the bits and pieces in the day-to-day, and then we aggregate it over a year, and you can look back. You can be like, "Oh yeah, I definitely see that theme in your work." STEPHANIE: Yeah, I'm glad you pointed that out. It is actually really interesting to see how something that we had talked about early, early on just had that thread throughout the year. And speaking of sustainability, we are taking a little break from the show to enjoy the holidays. We'll be off for a few weeks, and we will be back with a new Bike Shed in January. JOËL: Cheers to a new year. STEPHANIE: Yeah, cheers to a new year. Wrapping up 2023. And we will see you all in 2024. JOËL: On that note, shall we wrap up the whole year? STEPHANIE: Let's wrap up. Show notes for this episode can be found at bikeshed.fm. JOËL: This show has been produced and edited by Mandy Moore. STEPHANIE: If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter. STEPHANIE: Or reach both of us at hosts@bikeshed.fm via email. JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week. ALL: Byeeeeeee!!!!!!! AD: Did you know thoughtbot has a referral program? If you introduce us to someone looking for a design or development partner, we will compensate you if they decide to work with us. More info on our website at tbot.io/ referral. Or you can email us at referrals@thoughtbot.com with any questions.

Joël shares his experiences with handling JSON in a Postgres database. He talks about his challenges with ActiveRecord and JSONB columns, particularly the unexpected behavior of storing and retrieving JSON data. Stephanie shares her recent discovery of bookmarklets and highlights a bookmarklet named "Check This Out," which streamlines searching for books on Libby, an ebook and audiobook lending app. The conversation shifts to using constants in code as a form of documentation. Stephanie and Joël discuss how constants might not always accurately reflect current system behavior or logic, leading to potential misunderstandings and the importance of maintaining accurate documentation. Bookmarklets (https://www.freecodecamp.org/news/what-are-bookmarklets/) "Check This Out" Bookmarklet (https://checkthisout.today/) Libby (https://libbyapp.com/interview/welcome#doYouHaveACard) Productivity Tricks (https://www.bikeshed.fm/403) 12 Factor App Config (https://12factor.net/config) A Hierarchy of Documentation (https://challahscript.com/hiearchy_of_documentation) Sustainable Rails (https://sustainable-rails.com/) rails-erd gem (https://github.com/voormedia/rails-erd) Transcript STEPHANIE: Hello and welcome to another episode of the Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Stephanie Minn. JOËL: And I'm Joël Quenneville. And together, we're here to share a bit of what we've learned along the way. STEPHANIE: So, Joël, what's new in your world? JOËL: What's new in my world is JSON and how to deal with it in a Postgres database. So, I'm dealing with a situation where I have an ActiveRecord model, and one of the columns is a JSONB column. And, you know, ActiveRecord is really nice. You can just throw a bunch of different data at it, and it knows the column type, and it will do some conversions for you automatically. So, if I'm submitting a form and, you know, form values might come in as strings because, you know, I typed in a number in a text field, but ActiveRecord will automatically parse that into an integer because it knows we're saving that to an integer column. So, I don't need to do all these, like, manual conversions. Well, I have a form that has a string of JSON in it that I'm trying to save in a JSONB column. And I expected ActiveRecord to just parse that into a hash and store it in Postgres. That is not what happens. It just stores a raw string, so when I pull it out again, I don't have a hash. I have a raw string that I need to deal with. And I can't query it because, again, it is a raw string. So, that was a bit of an unexpected behavior that I saw there. STEPHANIE: Yeah, that is unexpected. So, is this a field that has been used for a while now? I'm kind of surprised that there hasn't been already some implementations for, like, deserializing it. JOËL: So, here's the thing: I don't think you can have an automatic deserialization there because there's no way of knowing whether or not you should be deserializing. The reason is that JSON is not just objects or, in Ruby parlance, hashes. You can also have arrays. But just raw numbers not wrapped in hashes are also valid JSON as are raw strings. And if I just give you a string and say, put this in a JSON field, you have no way of knowing, is this some serialized JSON that you need to deserialize and then save? Or is it just a string that you should save because strings are already JSON? So, that's kind of on you as the programmer to make that distinction because you can't tell at runtime which one of these it is. STEPHANIE: Yeah, you're right. I just realized it's [laughs] kind of, like, an anything goes [laughs] situation, not anything but strings are JSON, are valid JSON, yep [laughs]. That sounds like one of those things that's, like, not what you think about immediately when dealing with that kind of data structure, but... JOËL: Right. So, the idea that strings are valid JSON values, but also all JSON values can get serialized as strings. And so, you never know: are you dealing with an unserialized string that's just a JSON value, or are you dealing with some JSON blob that got serialized into a string? And only in one of those do you want to then serialize before writing into the database. STEPHANIE: So, have you come to a solution or a way to make your problem work? JOËL: So, the solution that I did is just calling a JSON parse before setting that attribute on my model because this value is coming in from a form. I believe I'm doing this when I'm defining the strong parameters for that particular form. I'm also transforming that string by parsing it into a hash with the JSON dot parse, which then gets passed to the model. And then I'm not sure what JSONB serializes as under the hood. When you give it a hash, it might store it as a string, but it might also have some kind of binary format or some internal AST that it uses for storage. I'm not sure what the implementation is. STEPHANIE: Are the values in the JSONB something that can be variable or dynamic? I've seen some people, you know, put that in getter so that it's just kind of done for you for anyone who needs to access that field. JOËL: Right now, there is a sort of semi-consistent schema to that. I think it will probably evolve to where I'll pull some of these out to be columns on the table. But it is right now kind of an everything else sort of dumping ground from an API. STEPHANIE: Yeah, that's okay, too, sometimes [laughs]. JOËL: Yeah. So, interesting journey into some of the fun edge cases of dealing with a format whose serialized form is also a valid instance of that format. What's been new in your world? STEPHANIE: So, I discovered something new that has been around on the internet for a while, but I just haven't been aware of it. Do you know what a bookmarklet is? JOËL: Oh, like a JavaScript code that runs in a bookmark? STEPHANIE: Yeah, exactly. So, you know, in your little browser bookmark where you might normally put a URL, you can actually stick some JavaScript in there. And it will run whenever you click your bookmark in your browser [chuckles]. So, that was a fun little internet tidbit that I just found out about. And the reason is because I stumbled upon a bookmarklet made by someone. It's called Check This Out. And what it does is there's another app/website called Libby that is used to check out ebooks and audiobooks for free from your local public library. And what this Check This Out bookmarklet does is you can kind of select any just, like, text on a web page, and then when you click the bookmarklet, it then just kind of sticks it into the query params for Libby's search engine. And it takes you straight to the results for that book or that author, and it saves you a few extra manual steps to go from finding out about a book to checking it out. So, that was really neat and cute. And I was really surprised that you could do that. I was like, whoa [laughs]. At first, I was like, is this okay? [laughs] If you, like, you can't read, you know, you don't know what the JavaScript is doing, I can see it being a little sketchy. But –- JOËL: Be careful of executing arbitrary JavaScript. STEPHANIE: Yeah, yeah. When I did look up bookmarklets, though, I kind of saw that it was, you know, just kind of a fun thing for people who might be learning to code for the first time to play around with. And some fun ideas they had for what you could do with it was turning all the font on a web page to Comic Sans [laughs]. So yeah, I thought that was really cute. JOËL: Has that inspired you to write your own? STEPHANIE: Well, we did an episode a while ago on productivity tricks. And I was thinking like, oh yeah, there's definitely some things that I could do to, you know, just stick some automated tasks that I have into a bookmarklet. And that could be a really fun kind of, like, old-school way of doing it, as opposed to, you know, coding my little snippets or getting into a new, like, Omnibar app [laughs]. JOËL: So, something that is maybe a little bit less effort than building yourself a browser extension or something like that. STEPHANIE: Yeah, exactly. JOËL: I had a client project once that involved a...I think it was, like, a five-step wizard or something like that. It was really tedious to step through it all to manually test things. And so, I wrote a bookmarklet that would just go through and fill out all the fields and hit submit on, like, five pages worth of these things. And if anything didn't work, it would just pause there, and then you could see it. In some way, it was moving towards the direction of, like, an automated like Capybara style test. But this was something that was helping for manual QA. So, that was a really fun use of a bookmarklet. STEPHANIE: Yeah, I like that. Like, just an in-between thing you could try to speed up that manual testing without getting into, like you said, an automated test framework for your browser. JOËL: The nice thing about that is that this could be used without having to set up pretty much anything, right? You paste a bit of JavaScript into your bookmark bar, and then you just click the button. That's all you need to do. No need to make sure that you've got Ruby installed on your machine or any of these other things that you would need for some kind of testing framework. You don't need Selenium. You don't need ChromeDriver. It just...it works. So, I was working...this was a greenfield startup project. So, I was working with a non-technical founder who didn't have all these things, you know, dev tooling on his machine. So, he wanted to try out things but not spend his days filling out forms. And so, having just a button he could click was a really nice shortcut. STEPHANIE: That's really cool. I like that a lot. I wasn't even thinking about how I might be able to bring that in more into just my daily work, as opposed to just something kind of fun. But that's an awesome idea. And I hope that maybe I'll have a good use for one in the future. JOËL: It feels like the thing that has a lot of potential, and yet I have not since written...I don't think I've written any bookmarklets for myself. It feels like it's the kind of thing where I should be able to do this for all sorts of fun tooling and just automate my life away. Somehow, I haven't done that. STEPHANIE: Bring back the bookmarklet [laughs]. That's what I have to say. JOËL: So, I mentioned earlier that I was working with a JSONB column and storing JSON on an ActiveRecord model. And then I wanted to interact with it, but the problem is that this JSON is somewhat arbitrary, and there are a lot of magic strings in there. All of the key names might change. And I was really concerned that if the schema of that JSON ever changed, if we changed some of the key names or something like that, we might accidentally break code in multiple parts of the app. So, I was very careful while building that model to quarantine any references to any raw strings only within that model, which meant that I leaned really heavily on constants. And, in some way, those constants end up kind of documenting what we think the schema of that JSON should be. And that got me thinking; you were telling me recently about a scenario where some code you were working with relied heavily on constants as a form of documentation, and that documentation kind of lied to you. STEPHANIE: Yeah, it did. And I think you mentioned something that I wanted to point out, which is that the magic strings that you think might change, and you wanted to pull that out into a constant, you know, so at least it's kind of defined in one place. And if it ever does change, you know, you don't have to change it in all of those places. And I do think that, normally, you know, if there's opportunities to extract those magic strings and give a name to them, that is beneficial. But I was gripping a little bit about when constants become, I guess, like, too wieldy, or there's just kind of, like, too much of a dependency on them as the things documenting how the app should work when it's constantly changing. I realized that I just used constant and constantly [laughs]. JOËL: The only constant is that it is not constant. STEPHANIE: Right. And so, the situation that I found myself in—this was on a client project a little bit ago—was that the constants became, like, gatekeepers of that logic where dev had to change it if the app's behavior changed, and maybe we wanted to change the value of it. And also, one thing that I noticed a lot was that we, as developers, were getting questions about, "Hey, like, how does this actually work?" Like, we were using the constants for things like pricing of products, for things like what is a compatible version for this feature. And because that was only documented in the code, other people who didn't have access to it actually were left in the dark. And because those were changing with somewhat frequency, I was just kind of realizing how that was no longer working for us. JOËL: Would you say that some of these values that we stored as constants were almost more like config rather than constants or maybe they're just straight-up application data? I can imagine something like price of an item you probably want that to be a value in the database that can be updated by an admin. And some of these other things maybe are more like config that you change through some kind of environment variable or something like that. STEPHANIE: Yeah, that's a good point. I do think that they evolved to become things that needed to be configured, right? I suppose maybe there wasn't as much information or foresight at the beginning of like, oh, this is something that we expect to change. But, you know, kind of when you're doing that first pass and you're told, like, hey, like, this value should be the price of something, or, like, the duration of something, or whatever that may be. It gets codified [chuckles]. And there is some amount of lift to change it from something that is, at first, just really just documenting what that decision was at the time to something that ends up evolving. JOËL: How would you draw a distinction between something that should be a constant versus something that maybe would be considered config or some other kind of value? Because it's pretty easy, right? As developers, we see magic numbers. We see magic strings. And our first thought is, oh, we've seen this problem before—constant. Do you have maybe a personal heuristic for when to reach for a constant versus when to reach for something else? STEPHANIE: Yeah, that's a good question. I think when I started to see it a lot was especially when the constants were arrays or hashes [laughs]. And I guess that is actually kind of a signal, right? You will likely be adding more stuff [laughs] into that data structure [laughs]. And, again, like, maybe it's okay, like, the first couple of times. But once you're seeing that request happen more frequently, that could be a good way to advocate for storing it in the database or, like, building a lightweight admin kind of thing so that people outside of the dev team can make those configuration changes. I think also just asking, right? Hey, like, how often do we suspect this will change? Or what's on the horizon for the product or the team where we might want to introduce a way to make the implementation a bit more flexible to something that, you know, we think we know now, but we might want to adjust for? JOËL: So, it's really about change and how much we think this might change in the future. STEPHANIE: Speaking of change, this actually kind of gets into the broader topic of documentation and how to document a changing and evolving entity [chuckles], you know, that being, like, the codebase or the way that decisions are made that impact how an application works. And you had shared, in preparation for this topic, an article that I read and enjoyed called Hierarchy of Documentation. And one thing that I liked about it is that it kind of presented all of the places that you could put information from, you know, straight in the code, to in your commit messages, to your issue management system, and to even wikis for your repo or your team. And I think that's actually something that we would want to share with new developers, you know, who might be wondering, like, where do I find or even put information? I really liked how it was kind of, like, laid out and gave, like, different reasons for where you might want to put something or not. JOËL: We think a lot about documentation as code writers. I'm curious what your experience is as a code reader. How do you tend to try to read code and understand documentation about how code works? And, apparently, the answer is, don't read the constants because these constants lie. STEPHANIE: I think you are onto something, though, because I was just thinking about how distrustful I've become of certain types of documentation. Like, when I think of code comments, on one hand, they should be a signal, right? They should kind of draw your attention to something maybe weird or just, like, something to note about the code that it's commenting on, or where it's kind of located in a file. But I sometimes tune them out, I'm not going to lie. When I see a really big block of code [chuckles] comment, I'm like, ugh, like, do I really have to read all of this? I'm also not positive that it's still relevant to the code below it, right? Like, I don't always have git blame, like, visually enabled in my editor. But oftentimes, when I do a little bit of digging, that comment is left over from maybe when that code was initially introduced. But, man, there have been lots of commits [chuckles] in the corresponding, you know, like, function sense, and I'm not really sure how relevant it is anymore. Do you struggle with the signal versus noise issue with code comments? How much do you trust them, and how much do you kind of, like, give credence to them? JOËL: I think I do tend to trust them with maybe some slight skepticism. It really depends on the codebase. Some codebases are really bad sort of comment hygiene and just the types of comments that they put in there, and then others are pretty good at it. The ones that I tend to particularly appreciate are where you have maybe some, like, weird function and you're like, what is going on here? And then you've got a nice, little paragraph up top explaining what's going on there, or maybe an explanation of ways you might be tempted to modify that piece of code and, like, why it is the way it is. So, like, hey, you might be wanting to add an extra branch here to cover this edge case. Don't do that. We tried it, and it causes problems for XY reasons. And sometimes it might be, like, a performance thing where you say, look, the code quality person in you is going to look at this and say, hey, this is hard to read. It would be better if we did this more kind of normalized form. Know that we've particularly written this in a way that's hard to read because it is more performant, and here are the numbers. This is why we want it in this way. Here's a link to maybe the issue, or the commit, or whatever where this happened. And then if you want to start that discussion up again and say, "Hey, do we really need performance here at the cost of readability?", you can start it up again. But at least you're not going to just be like, oh, while I'm here, I'm going to clean up this messy code and accidentally cause a regression. STEPHANIE: Yeah. I like what you said about comment hygiene being definitely just kind of, like, variable depending on the culture and the codebase. JOËL: I feel like, for myself, I used to be pretty far on the spectrum of no comments. If I feel the need to write a comment, that's a smell. I should find other ways to communicate that information. And I think I went pretty far down that extreme, and then I've been slowly kind of coming back. And I've probably kind of passed the center, where now I'm, like, slightly leaning towards comments are actually nice sometimes. And they are now a part of my toolkit. So, we'll see if I keep going there. Maybe I'll hit some point where I realize that I'm putting too much work into comments or comments are not being helpful, and I need to come back towards the center again and focus on other ways of communicating. But right now, I'm in that phase of doing more comments than I used to. How about you? Where do you stand on that sort of spectrum of all information should be communicated in code tokens versus comments? STEPHANIE: Yeah, I think I'm also somewhere in the middle. I think I have developed an intuition of when it feels useful, right? In my gut, I'm like, oh, I'm doing something weird. I wish I didn't have to do this [chuckles]. I think it's another kind of intuition that I have now. I might leave a comment about why, and I think that is more of that signal, right? Though I also recently have been using them more as just, like, personal notes for myself as I'm, you know, in my normal development workflow, and then I will end up cleaning them up later. I was working on a codebase where there was a soft delete functionality. And that was just, like, a concern that was included in some of the models. And I didn't realize that that's what was going on. So, when I, you know, I was calling destroy, I thought it was actually being deleted, and it turns out it wasn't. And so, that was when I left a little comment for myself that was like, "Hey, like, this is soft deleted." And some of those things I do end up leaving if I'm like, yes, other people won't have the same context as me. And then if it's something that, like, well, people who work in this app should know that they have soft delete, so then I'll go ahead and clean that up, even though it had been useful for me at the time. JOËL: Do you capture that information and then put it somewhere else then? Or is it just it was useful for you as a stepping-stone on the journey but then you don't need it at the end and nobody else needs to care about it? STEPHANIE: Oh, you know what? That's actually a really great point. I don't think I had considered saving that information. I had only thought about it as, you know, just stuff for me in this particular moment in time. But that would be really great information to pull out and put somewhere else [chuckles], perhaps in something like a wiki, or like a README, or somewhere that documents things about the system as a whole. Yeah, should we get into how to document kind of, like, bigger-picture stuff? JOËL: How do you feel about wikis? Because I feel like I've got a bit of a love-hate relationship with them. STEPHANIE: I've seen a couple of different flavors of them, right? Sometimes you have your GitHub wiki. Sometimes you have your Confluence ecosystem [laughs]. I have found that they work better if they're smaller [laughs], where you can actually, like, navigate them pretty well, and you have a sense of what is in there, as opposed to it just being this huge knowledge base that ends up actually, I think, working against you a little bit [laughs]. Because so much information gets duplicated if it's hard to find and people start contributing to it maybe without keeping in mind, like, the audience, right? I've seen a lot of people putting in, like, their own personal little scripts [laughs] in a wiki, and it works for them but then doesn't end up working for really anyone else. What's your love-hate relationship to them? JOËL: I think it's similar to what you were saying, a little bit of structure is nice. When they've just become dumping grounds of information that is maybe not up to date because over the course of several years, you end up with a lot of maybe conflicting articles, and you don't know which one is the right thing to do, it becomes hard to find things. So, when it just becomes a dumping ground for random information related to the company or the app, sometimes it becomes really challenging to find the information I need and to find information that's relevant, to the point where oftentimes looking something up in the wiki is my last resort. Like, I'm hoping I will find the answer to my question elsewhere and only fallback to the wiki if I can't. STEPHANIE: Yeah, that's, like, the sign that the wiki is really not trustworthy. And it kind of is diminishing returns from there a bit. I think I fell into this experience on my last project where it was a really, really big wiki for a really big codebase for a lot of developers. And there was kind of a bit of a tragedy of the commons situation, where on one hand, there were some things that were so manual that the steps needed to be very explicitly documented, but then they didn't work a lot of the time [laughs]. But it was hard to tell if they weren't working for you or because it was genuinely something wrong with, like, the way the documentation laid out the steps. And it was kind of like, well, I'm going to fix it for myself, but I don't know how to fix it for everyone else. So, I don't feel confident in updating this information. JOËL: I think that's what's really nice about the article that you mentioned about the hierarchy of documentation. It's that all of these different forms—code, comments, commit messages, pull requests, wikis—they don't have to be mutually exclusive. But sometimes they work sort of in addition to each other sort of each adding more context. But also, sometimes it's you sort of choose the one that's the highest up on that list that makes sense for what you're trying to do, so something like documenting a series of steps to do something maybe a wiki is a good place for that. But maybe it's better to have that be executable. Could that be a script somewhere? And then maybe that can be a thing that is almost, like, living documentation, but also where you don't need to maybe even think about the individual steps anymore because the script is running, you know, 10 different things. And I think that's something that I really appreciated from the book Sustainable Rails is there's a whole section there talking about the value of setup scripts and how people who are getting started on your app don't want to have to care about all the different things to set it up, just run a script. And also, that becomes living documentation for what the app needs, as opposed to maybe having a bulleted list with 10 elements in it in your project README. STEPHANIE: Yeah, absolutely. In the vein of living documentation, I think one thing that wikis can be kind of nice for is for putting visual supplements. So, I've seen them have, like, really great graphs. But at the same time, you could use a gem like Rails-ERD that generates the entity relationship diagram as the schema of your database changes, right? So, it's always up to date. I've seen that work well, too, when you want to have, like I said, those, like, system-level documentation that sometimes they do change frequently and, you know, sometimes they don't. But that's definitely worth keeping in mind when you choose, like, how you want to have that exist as information. JOËL: How do you feel about deleting documentation? Because I feel like we put so much work into writing documentation, kind of like we do when writing tests. It feels like more is always better. Do you ever go back and maybe sort of prune some of your docs, or try to delete some things that you think might no longer be relevant or helpful? STEPHANIE: I was also thinking of tests when you first posed that question. I don't know if I have it in my practice to, like, set aside time and be like, hmm, like, what looks outdated these days? I am starting to feel more confident in deleting things as I come across them if I'm like, I just completely ignored this or, like, this was just straight up wrong [laughs]. You know, that can be scary at first when you aren't sure if you can make that determination. But rather than thrust that, you know, someone else going through that same process of spending time, you know, trying to think about if this information was useful or not, you can just delete it [laughs]. You can just delete tests that have been skipped for months because they don't work. Like, you can delete information that's just no longer relevant and, in some ways, causing you more pain because they are cluttering up your wiki ecosystem so that no one [laughs] feels that any of that information is relevant anymore. JOËL: I'll be honest, I don't think I've ever deleted a wiki article that was out of date or no longer relevant. I think probably the most I've done is go to Slack and complain about how an out-of-date wiki page led me down the wrong path, which is probably not the most productive way to channel those feelings. So, maybe I should have just gone back and deleted the wiki page. STEPHANIE: I do like to give a heads up, I think. It's like, "Hey, I want to delete this thing. Are there any qualms?" And if no one on your team can see a reason to keep it and you feel good about that it's not really, like, serving its purpose, I don't know, maybe consider just doing it. JOËL: To kind of wrap up this topic, I've got a spicy question for you. STEPHANIE: Okay, I'm ready. JOËL: Do you think that AI is going to radically change the way that we interact with documentation? Imagine you have an LLM that you train on maybe not just your code but the Git history. It has all the Git comments and maybe your wiki. And then, you can just ask it, "Why does function foo do this thing?" And it will reference a commit message or find the correct wiki article. Do you think that's the future of understanding codebases? STEPHANIE: I don't know. I'm aware that some people kind of can see that as a use case for LLMs, but I think I'm still a little bit nervous about the not knowing how they got there kind of part of it where, you know, yes, like I am doing this manual labor of trying to sort out, like, is this information good or trustworthy or not? But at least that is something I'm determining for myself. So, that is where my skepticism comes in a little bit. But I also haven't really seen what it can do yet or seen the outcomes of it. So, that's kind of where I'm at right now. JOËL: So, you think, for you, the sort of the journey of trying to find and understand the documentation is a sort of necessary part of building the understanding of what the code is doing. STEPHANIE: I think it can be. Also, I don't know, maybe my life would be better by having all that cut out for me, or I could be burned by it because it turns out that it was bad information [laughs]. So, I can't say for sure. On that note, shall we wrap up? JOËL: Let's wrap up. STEPHANIE: Show notes for this episode can be found at bikeshed.fm. JOËL: This show has been produced and edited by Mandy Moore. STEPHANIE: If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter. STEPHANIE: Or reach both of us at hosts@bikeshed.fm via email. JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week. ALL: Byeeeeeeee!!!!!! AD: Did you know thoughtbot has a referral program? If you introduce us to someone looking for a design or development partner, we will compensate you if they decide to work with us. More info on our website at: tbot.io/referral. Or you can email us at: referrals@thoughtbot.com with any questions.

Stephanie recommends "Blue Eye Samurai" and a new ceramic pot (donabe) for cooking. Joël talks about the joy of holding a warm beverage in a unique mug. Stephanie discusses her shift to a part-time support and maintenance role at thoughtbot, contrasting it with her full-time development work. She highlights the importance of communication, documentation, and workplace flexibility in this role. Stephanie appreciates the professional growth opportunities and aligns this flexible work style with her long-term career goals. Blue Eye Samurai (https://www.netflix.com/title/81144203) Donabe pots (https://jinenstore.com/collections/nagatani-en) thoughtbot’s Support & Maintenance services (https://thoughtbot.com/services/rails-maintenance) Transcript: JOËL: Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Joël Quenneville. STEPHANIE: And I'm Stephanie Minn. And together, we're here to share a bit of what we've learned along the way. JOËL: So, Stephanie, what's new in your world? STEPHANIE: I have a TV show recommendation this week. I think this is my first time having TV or movies to recommend, so this will be fun. My partner and I just finished watching Blue Eye Samurai on Netflix, which is an animated historical Samurai drama. But the really cool thing about it is that the protagonist she's a woman who is disguising herself as a man, and she is half Japanese and half White, which the show takes place during Edo, Japan. And so that was a time when Japan was locked down, and there were no outsiders allowed in the country. And so, to be mixed race like that was to be, like, kind of, like, demonized and to be really excluded and shamed. And so, the main character is on, like, a revenge mission. And it was such a cool show. I was kind of, like, on the edge of my seat the whole time. And it's very beautifully animated. There were just a lot of really awesome things about it. And I think it's very different from what I've been seeing on TV these days. JOËL: Is this a single-season show? STEPHANIE: So far, there's just one season. I think it's pretty new, yeah. It's very watchable in a couple of weekends. [laughter] JOËL: Dangerously so. STEPHANIE: Yeah, exactly [laughs]. JOËL: How do you feel about the way they end the arc in season one? Do they kind of leave you on a cliffhanger, or does it feel like a pretty satisfying place? STEPHANIE: Ooh, I think both, which is the sweet spot, in my opinion, where it's not, like, cliffhanger for the sake of, like, ugh, now I feel like I have to just watch the next part to see what happens because I was left unsatisfied. I like when seasons are kind of like chapters of the story, right? And the characters are also well written, too, and really fleshed out even, you know, some of the side characters. They all have their arcs that are really satisfying. And, again, I just was left very impressed. JOËL: I guess that's the power of good storytelling. STEPHANIE: Yeah. I was reading a review of the show. And that was kind of the theme of–it was just that, like, this is really good storytelling, and I would have to agree. Yeah, I highly recommend checking it out. It was very fun. It was very bloody, but [chuckles], for me, it being animated actually made it a little more palatable for me [laughs]. The fight scenes, the action scenes were really cool. I think the way that it's been described is kind of, like, you know, if you like historical dramas, or if you like things like Game of Thrones, there's kind of something for everyone. I recommend checking it out. Joël, what's new in your world? JOËL: Listeners of the show don't know this, but you and I are on a video call while we're recording this. And you'd commented earlier that I was holding a cool mug. It's got a rock climbing hold as a handle, which is pretty fun. I enjoy a lot of bouldering. That makes it a fun mug. But I was recently thinking about just how much pleasure I get from holding a mug with a warm beverage. It's such a small thing, but it makes me so happy. And that got me thinking more broadly about what are things in life that are kind of like that. They're small things that have, like, an outsized impact on your happiness. Do you have anything like that? STEPHANIE: Oh yes, absolutely. You were talking about the warmth of a hot beverage in your hands. And I was thinking about something similar, too, because I'm pretty sure this time of year last year, I talked about something that was new in my world that was just, like, a thing that I got to make winter more tolerable for me here in Chicago, and I think it was, like, a heated blanket [laughs]. And I am similarly in that space this year of like, what can I do or get to make this winter better than last winter? So, this year, what I got that I'm really excited to use— it actually just came in the mail—is this ceramic pot called the donabe that's kind of mainly used for Japanese cooking, especially, like, hot pot. And so, it will be a huge improvement to my soup game this year [laughs]. Similarly, it's kind of, like, one of those small things where you can take it from the stovetop where you're cooking straight to the table, and I'm so looking forward to that. It's kind of like your hot beverage in your hand but, like, three times the size [laughs]. JOËL: Right. The family-style version of it. STEPHANIE: Yeah, exactly. So, that's what I'm really looking forward to this year as something that is just, like, I don't know, a little small upgrade to my regular soup routine. But I think I will get a lot of pleasure [laughs] out of it. JOËL: What do you normally cook in that style of pot? Is it typically you do a hot pot in there, or is it meant for soups? STEPHANIE: Yeah, it holds heat really well, so I think that's why it's used for soup a lot. And the one that I got specifically has a little ceramic steamer plate as well. And so, I'm looking forward to having, like, this setup that's made for steaming, where you don't have to have any, like, too many extra bits. And, again, it can go from stove to table, and that's one less thing I [chuckles] need to wash. JOËL: I love it. So, something else that is kind of new in your world is you'd mentioned on a recent episode you'd wrapped up with your current client. And you've rotated on to not exactly a new client but a new almost line of business. You're doing a rotation with our support and maintenance team. Can you tell us a little bit about what that is like? STEPHANIE: Yeah. I'm excited to share more about it because this is my first time on this team doing this work. And it's pretty new for thoughtbot, too. I think it's only, like, a year old that we have had this sub-team of the one that you and I are on, Boost. In the sub-team, support and maintenance is focused on providing flexible part-time work for clients who are just needing some dedicated hours, not necessarily for, you know, a lot of, like, intense new feature work, but making sure that things are running smoothly. A lot of the clients, you know, have had Rails apps that are several years old, that are chugging along [chuckles], just need that, like, attention every now and then to make sure that upgrades are happening, fix any bugs, kind of as the app just continues to work and provide value. And then, occasionally, there is a little bit of feature work. But the interesting thing about being on this team is that instead of being on one client full-time, you are working on a lot of different clients at the same time, and a lot of them are on retainers. So, they maybe have, like, 20 hours a month of work that gets filled with kind of whatever tasks need to be done during that time. So yeah, I recently joined a few days ago and have been very surprised by kind of this style of work. It's different from what I'm used to. JOËL: That seems pretty different than the sort of traditional thoughtbot client engagement. Typically, if I'm a client and I'm hiring a team from thoughtbot, as a client, I get sort of a dedicated team. And they're probably either building some things for me or maybe working with my team and sort of full-time building features. Whereas if I hire the support and maintenance team, it sounds like it's a bit more ad hoc. And it's things I assume it's like, oh, we probably need to upgrade our Rails version since a new release came out last month. Can you do that? Here's a small bug that was reported. Can somebody fix that? Things along those lines. Is that pretty approximate of what the experience is for a client? STEPHANIE: Yeah, I would say so. I think the other surprising thing has been there have been a little bit of more DevOps type of tasks as well mixed in there. Because oftentimes, these are smaller clients who maybe have, like, a few developers actively working on new features and that type of stuff. But there is, like, so much of the connecting work that needs to happen when you have an application. And if you don't have a full in-house team for that, that often gets put on developers' plates. But it's kind of nice to have this flexible support and maintenance team, again, to, like, do the work as it comes up. A lot of it is not necessarily, like, stuff that can be planned in advance. It's kind of like, oh, we're hitting, like, our usage limit for this Heroku add-on. Let's evaluate if this is still working for us, if this is a good tier to be on. Like, should we upgrade? Are there other levers we could pull or adjustments we can make? So, that's actually been some of the stuff that I've been working on, too, which is, again, a little bit different from normal development work but also still very much related. And it's all kind of part of the job. And, you know, a lot of the skills are transferable. And to know how to do development in a framework then sets you up, I think, really well to, like, be able to make those kinds of evaluations. JOËL: So, it sounds like you almost, in a sense, provide a bit of a velocity cushion for clients so that if something does come up where they would maybe normally need to pull a dev off of feature work to do some side thing for a couple of days, you can come in and handle that so that their dev team stays focused on shipping features. STEPHANIE: Yeah, I like that phrase you used: velocity cushion. That's cool. I like it. The other surprising thing that I have kind of quite enjoyed, at least for now, is because we bill a little bit differently on this work; we have to track our hours more explicitly. And that has actually helped me focus a lot more on what I'm doing and if I should continue to be doing what I'm doing. I'm timeboxing things a lot more because I know that if there is a ceiling on the number of hours, I want to make sure that that time is spent in the most valuable way. And I also really enjoy, like, the boundaries of timeboxing, yes, but also, like, the tasks are usually scoped pretty narrowly so that they are things that you can accomplish, definitely in the week, because you don't know if you'll kind of still be working for this client next week but even more so, like, within a few days. And that is nice because I can kind of, like, you know, track my hours, finish the task, and then feel a little bit more free to go do something else without being, like, okay, like, what's the next thing that I need to be doing? There's a little bit more freedom, I think, when you're kind of, like, optimizing towards, like, finishing each item. JOËL: Do the stories of the work that you have to do does it typically come kind of pre-scoped? Are you involved in making sure that it has, like, very aggressive scoping? STEPHANIE: Yeah. So far, I've not been involved in doing the scoping work, and it has come pre-scoped, which has been nice. This was also, again, just different. Because I was on a client team previously, a lot of the work to be done was the disambiguating, the, like, figuring out what to be doing. Whereas here, because, again, we're kind of optimized for people coming in and out, if there is uncertainty or lack of clarity, it's pointed out early, and someone is like, "Okay, I will take care of this. Like, I'll take the lead on this so that it can be handed off." One client that I'm working on is using Basecamp's Shape Up methodology, which I actually hadn't worked with in a very explicit way before. And that has been interesting to learn about a little bit, too. One thing that I have enjoyed about it is instead of sprints, they're called cycles. And I like that a lot because, you know, sprints kind of have the connotation of, like, you're running as fast as you can but also, like, you can't run that way forever [laughs]. And so, even that, like, little bit of rewording change is really nice. The variable part is scope, right? It's we're focused on delivering something completely and very intentionally cutting scope as kind of the main lever. JOËL: How do you maintain sort of focus and flow if you're jumping across multiple clients? Because you said, you work with multiple clients as part of this team. And I feel like I can get a little bit frustrated sometimes, even just jumping between, like, tickets within one project. And so, I could imagine that jumping between different clients during the week or even the day might be really disruptive. Have you found techniques to help you stay in the flow? STEPHANIE: Yeah, that is a tough one because, also, every client has their different application; you then have to start up on [laughs] your local machine, and that is kind of annoying. You know, I do still tend to kind of, like, bundle similar work together. If, like, there's a few things I can do for a client on one day, I'll make sure to focus on that. But what I mentioned earlier about, like, seeing something to completion has been really, I want to say, fun even. Because it then kind of, like, frees up that mental space of, like, okay, I don't have to, like, have this thing that I'm working on lingering in my head about, like, oh, did I forget to do something? Or, you know, have, like, shower thoughts of like, oh, I just thought of a new way to implement this [laughs] feature because it doesn't spill over as much as maybe larger initiatives anyway. And so, I am context-switching, but it's only kind of after I've gotten something to a good place where I've left all of the notes. And that's another thing that I'm now kind of compelled to do a little more actively. It's like, every single day, I'm kind of making sure that the work that I've done has been reported on, one, because I have to track my hours, so, you know, and I sometimes leave notes about what that time was spent on doing. And also, when the expectation is that someone else will be picking up, then there's no, like, oh, like, let me hold on to this, and only when I know that I have to hand off something that's when I'll do the, like, dedicated knowledge dumping. It's kind of just built into the process a little more frequently. JOËL: So, you're setting up for, like, an imminent vacation factor. STEPHANIE: Yeah. Which I kind of like because then I can take a vacation [laughs] whenever I want and not have to worry too much about, oh, did I do everything I needed to do before I leave? JOËL: So, you know, these practices that you're doing are specifically adapted for the style of work that you have. Are there any that you think you would bring to your own practice if you ever rotated back on to a dedicated client project, anything that you would do there that you would want to include from your practice here? STEPHANIE: Yeah. It does sound kind of weird because part of what's nice about being on a full-time team is that there is less, oh, if I don't get something done today, I have tomorrow to do it [laughs]. And it seems like that would be like, oh, like, kind of take the pressure off a little bit. But I would be really curious to continue having, like, such an intense awareness about how I'm spending my time. Because I've certainly gotten a little bit lax on, like, full-time development work when you just go down a rabbit hole [laughs] and you come out, like, three hours later, and you're like, "What did I just do?" [laughs] And, you know, maybe that's what needed to be done, and that's fine. But if you have the information that it took you three hours, you can at least make a better-informed decision about, like, oh, maybe I should have stopped a little earlier or, like, yeah, it took about three hours, and that's okay. I think that would be an interesting area to incorporate and to be able to report more frequently. And I also like to know how other people spend their time, too. So, just, like, that sharing of information would also be really beneficial even to, like, a team. JOËL: What about the more aggressive documentation? Is that something that...because that can be really time-consuming, I imagine, as well. Is that something that you would value in a kind of, more focused full-time project context? STEPHANIE: Yeah. One part I've enjoyed about it is that I'm documenting, like, decision-making a lot more actively where, you know, I'm kind of, like, surfacing to be like, hey, here's the outcomes of, like, my research. We're not as, you know, embedded in the business, and we don't have as much of that, like, context and knowledge about what the best solutions are all the time. I'm documenting all of that, you know, usually, for the client stakeholder to be like, "Hey, here's my recommendations, like, how do you want to...what do you think is the best way to go? On one hand, it's kind of nice not to have to, like, be solely responsible for making that decision, right? And I'm kind of, like, leaning on, like, hey, like, you're the expert of your application and your product, you know, here's what I've learned. And now I've, like, put this all, like, for you and presented it to you. And I think that, for me, has gotten lost sometimes when I end up being the same person of, like, doing the research and then deciding, and it just kind of ends up being held in my head. And that, I think, is something really important to document, even if it's just for other people to, like, see how that process might work or, like, what things I already considered or didn't try. That exercise, I think, can be really important. So, so far, the documentation has not necessarily been, like, code level, but more, like, for each task, it's, like, showing your work, right? And not in a, like, you're being monitored [laughs] sort of way but in a way that supports it getting done with a lot of that turnover. JOËL: It's almost like a mini report that you're doing. So, you'd mentioned, for example, an application running into memory problems on Heroku. It sounds like you would then go maybe investigate that and then make some recommendations on whether they need to increase some dynos or maybe make some internal changes. It sounds like you may or may not be the one to execute those changes. But you would write up some, like, a mini report and submit that to the client, and then they can make their own execution choices. STEPHANIE: Yeah, exactly. And they can execute it themselves or then create a new ticket for the next person rotating on to support and maintenance to tackle it in a different cycle. JOËL: So, support and maintenance doesn't just do the investigation. Your team might do the execution as well. It's just that the sort of more research-y stuff and the execution stuff gets split out into different tickets because it's so tightly scoped. STEPHANIE: Yeah, that sounds right. JOËL: I like that. STEPHANIE: One area that I wasn't sure that I was going to like so much about this kind of work is, you know, when you're not kind of embedded on a team, I was thinking that I might not feel as connected, or I would miss a bit of that getting to know people and just, like, seeing people face to face on a daily basis. I'm still evaluating how that would go so far because it has definitely been, like, mostly asynchronous communication, you know, which is what works well for this type of the style of team or project. But I think what has been helpful is realizing that, like, oh yeah, like, I can also get that elsewhere, you know, with thoughtbot folks like with you doing this podcast every week. And right now, there are, like, two Boost members who are doing support and maintenance full time, and folks who are unbooked kind of come in and out. And I can see that there's still a team. So, it's not nearly as kind of, like, isolating as what I had thought it would be. JOËL: There's something that's really curious to me, I think, sitting at the intersection of the idea of fostering more team interactions and the sort of, like, mini reports that you write. And that's that I would love to see more sharing among all of us at thoughtbot about different interesting problems that we've had to solve or that we're tackling on different client work. Because I think in that case, it's a situation where we all just learn something, you know, maybe I've never had to deal with a memory leak or might not even have an idea of, like, how to approach memory issues on Heroku. So, seeing your little mini report, if you'd maybe share that, and, you know, maybe it can be anonymized in some way if needs to, I think would be really nice, at the very least, something that could be done, like, internally. So, I almost wonder if, like, building that practice of, you know, maybe not for every ticket that I do because, you know, I don't want to just be dumping my tickets in the thoughtbot Slack. But I run into something interesting and be like, oh, let me tell a little story about this and do a little write-up. That might be something that's good for the whole team and not just for folks who are on support and maintenance. STEPHANIE: Yeah, absolutely. As you were saying that, I was thinking about how it does kind of encourage me to find support outside of my, like, immediate team, right? Because I don't necessarily have one with the client and to, I don't know, I'm imagining, like, these roots growing in terms of different communities I'm a part of and bringing those problems just outside of my internal world, and kind of getting that outside feedback because by necessity a little bit, right? But also, with the added benefit of, you know, I think that's also how a lot of people end up writing content that gets shared with the world. So, I had the misconception that I would be kind of just, like, on my own off doing things like just tickets and being a little coding robot, but I've been surprised by it feels very fresh and new. So, I think, I guess, I was needing a little bit of that [laughs]. JOËL: I was having a conversation with another thoughtboter recently about how valuable sometimes change can be for its own sake and how that can sort of refresh. You want it just at the rate where you have a chance to build some stability. You don't want chaos. But sometimes change can sort of take you out of a rut, give you energy, maybe sort of restart some good habits that you had sort of let atrophy. And that finding, like, just that right level of shaking things up can really help a team, you know, get their effectiveness to the next level. STEPHANIE: Yeah. I like what you said about good habits, for sure. A couple of other random, little things that I just thought of about what I've liked is, I don't know, maybe this is a little silly. But we, you know, use shared credentials for logging into different services and applications or third parties that clients are using. And that has actually been something that has been so easy [laughs] and very low friction compared to, you know, joining a new project and manually be added as, like, your individual account to all of the different things. And things inevitably get forgotten, and then you have to rely on someone else to do it. And sometimes they don't get back to you [laughs] for a while. The self-serviceness of this work has been cool, too. And I just, yeah, wanted to say that I really appreciated the thought that went into making it as easy as possible to be like, yeah, I can find the credentials here. It is, you know, a bit more anonymized because I'm just using, like, a shared account. JOËL: Like a generic thoughtbot account on a client system rather than stephanie@thoughtbot. STEPHANIE: Yeah, exactly. But I think I saved so much time [laughs] this week just being able to do all of that myself and, you know, knowing where to look first before having to ask. JOËL: I guess you'd need something like that, right? If you're only jumping in on a project for the first time, for a couple of hours or something like that, you don't want to go through a whole onboarding process because that might then, like, easily double. You know, instead of doing two hours on this project, you're now doing four. STEPHANIE: Yeah, exactly. I guess the other takeaway, for me, was like, oh, definitely, if I were to have to set up accounts [laughs] for an application, you know, I've obviously seen where it was like, very clearly, like, the founder having created all these personal accounts for this services, and people are still using their credentials many years later [laughs], even though they probably, like, maybe may not even work for the company anymore. But yeah, the shared credentials and using that generic account that anyone can kind of get into when needed has really lowered the barrier to jump into doing that work, right? And especially because, like you said, it reduces that time. And we're, you know, billing by the hour anyway. So, it's kind of a win-win situation. JOËL: And I totally understand why you would not want something like that for a longer engagement. But for something like support and maintenance, it sounds like it was the right choice. STEPHANIE: Yeah, yeah. Again, I just mentioned it because it's just different. And so, maybe if this sparks any ideas for our listeners about how processes could be different or, like, the styles or ways of working can be different, I think that would be cool. JOËL: And just to be clear here, it sounds like what you're doing is for sort of each client; you create a separate set of credentials that are for that client but that are about thoughtbot generically. You don't have, like, one thoughtbot email and password that we reuse for every client. STEPHANIE: [laughs] Oh yes. That would be not so good [laughs] if we got hacked and suddenly, now they have access to everything. JOËL: So, every client gets its own unique email password combo. We're using security best practices here. And then, since you do have to share them through a team, are you doing some sort of, like, shared 1Password vault or something along those lines? STEPHANIE: Yeah, we are using a shared 1Password vault. That is definitely what I meant [laughs] the first time when I was mentioning the shared credentials, where that was basically the only thing I had to get onboarded to, the vault, for support and maintenance to be able to hit the ground running. JOËL: So, this sounds like a pretty exciting new style of project for you. Is this something that you would see yourself preferring to do longer term, to sort of focus on this style of project? Or do you think that you'd like to come back to more classic project work in the near future? STEPHANIE: I'm not sure yet, but I'm also hoping to have an answer to that question. And it definitely does feel like an experiment for me personally. I can see liking it, and that also fitting well with some of my longer-term goals of being able to, like, step back from work. Maybe working fewer days a week is something that I've, like, thought about in terms of, like, a long-term goal of mine because I'm not as needed [laughs] on a team. Which I think, in the past, I also had a bit of a misconception that, like, in order to be a good developer, I had to have all the domain knowledge, and be indispensable, and, like, be the go-to person to answer all the questions. But now I'm at a point where I don't want to [laughs] necessarily have to answer, like, every question because that creates, like, a dependency on me. And if I need to step away from work, then that could be tough, right? The vacation factor that you mentioned. So, this style of work is very interesting in terms of if it might provide me a little bit more of that, not exactly work-life balance, but just kind of be closer to my goals in terms of what I want out of work and my time. And, hopefully, I'm going to be doing this next week, but I don't know because that's the nature of it [laughs]. But if I am, then I'll definitely have more to say about it. Probably. JOËL: Well, it definitely sounds like we'll have to check in again on what's, I guess, not so new in your world on a future episode. On that note, shall we wrap up? STEPHANIE: Let's wrap up. Show notes for this episode can be found at bikeshed.fm. JOËL: This show has been produced and edited by Mandy Moore. STEPHANIE: If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter. STEPHANIE: Or reach both of us at hosts@bikeshed.fm via email. JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week. ALL: Byeeeeeeee!!!!!! AD: Did you know thoughtbot has a referral program? If you introduce us to someone looking for a design or development partner, we will compensate you if they decide to work with us. More info on our website at: tbot.io/referral. Or you can email us at referrals@thoughtbot.com with any questions.

Joël recaps his time at RubyConf! He shares insights from his talk about different aspects of time in software development, emphasizing the interaction with the audience and the importance of post-talk discussions. Stephanie talks about wrapping up a long-term client project, the benefits of change and variety in consulting, and maintaining a balance between project engagement and avoiding burnout. They also discuss strategies for maintaining work-life balance, such as physical separation and device management, particularly in a remote work environment. Rubyconf (https://rubyconf.org/) Joël’s talk slides (https://speakerdeck.com/joelq/which-time-is-it) Flaky test summary slide (https://speakerdeck.com/aridlehoover/the-secret-ingredient-how-to-understand-and-resolve-just-about-any-flaky-test?slide=170) Transcript: STEPHANIE: Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Stephanie Minn. JOËL: And I'm Joël Quenneville. And together, we're here to share a bit of what we've learned along the way. STEPHANIE: So, Joël, what's new in your world? JOËL: Well, as of this recording, I have just gotten back from spending the week in San Diego for RubyConf. STEPHANIE: Yay, so fun. JOËL: It's always so much fun to connect with the community over there, talk to other people from different companies who work in Ruby, to be inspired by the talks. This year, I was speaking, so I gave a talk on time and how it's not a single thing but multiple different quantities. In particular, I distinguish between a moment in time like a point, a duration and amount of time, and then a time of day, which is time unconnected to a particular day, and how those all connect together in the software that we write. STEPHANIE: Awesome. How did it go? How was it received? JOËL: It was very well received. I got a lot of people come up to me afterwards and make a variety of time puns, which those are so easy to make. I had to hold myself back not to put too many in the talk itself. I think I kept it pretty clean. There were definitely a couple of time puns in the description of the talk, though. STEPHANIE: Yeah, absolutely. You have to keep some in there. But I hear you that you don't want it to become too punny [laughs]. What I really love about conferences, and we've talked a little bit about this before, is the, you know, like, engagement and being able to connect with people. And you give a talk, but then that ends up leading to a lot of, like, discussions about it and related topics afterwards in the hallway or sitting together over a meal. JOËL: I like to, in my talks, give little kind of hooks for people who want to have those conversations in the hallway. You know, sometimes it's intimidating to just go up to a speaker and be like, oh, I want to, like, dig into their talk a little bit. But I don't have anything to say other than just, like, "I liked your talk." So, if there's any sort of side trails I had to cut for the talk, I might give a shout-out to it and say, "Hey, if you want to learn more about this aspect, come talk to me afterwards." So, one thing that I put in this particular talk was like, "Hey, we're looking at these different graphical ways to think about time. These are similar to but not the same as thinking of time as a one-dimensional vector and applying vector math to it, which is a whole other side topic. If you want to nerd out about that, come find me in the hallway afterwards, and I'd love to go deeper on it." And yeah, some people did. STEPHANIE: That's really smart. I like that a lot. You're inviting more conversation about it, which I know, like, you also really enjoy just, like, taking it further or, like, caring about other people's experiences or their thoughts about vector math [laughs]. JOËL: I think it serves two purposes, right? It allows people to connect with me as a speaker. And it also allows me to feel better about pruning certain parts of my talk and saying, look, this didn't make sense to keep in the talk, but it's cool material. I'd love to have a continuing conversation about this. So, here's a path we could have taken. I'm choosing not to, as a speaker, but if you want to take that branch with me, let's have that afterwards in the hallway. STEPHANIE: Yeah. Or even as, like, new content for yourself or for someone else to take with them if they want to explore that further because, you know, there's always something more to explore [chuckles]. JOËL: I've absolutely done that with past talks. I've taken a thing I had to prune and turned it into a blog post. A recent example of that was when I gave a talk at RailsConf Portland, which I guess is not so recent. I was talking about ways to deal with a test suite that's making too many database requests. And talking about how sometimes misusing let in your RSpec tests can lead to more database requests than you expect. And I had a whole section about how to better understand what database requests will actually be made by a series of let expressions and dealing with the eager versus lazy and all of that. I had to cut it. But I was then able to make a blog post about it and then talk about this really cool technique involving dependency graphs. And that was really fun. So, that was a thing where I was able to say, look, here's some content that didn't make it into the talk because I needed to focus on other things. But as its own little, like, side piece of content, it absolutely works, and here's a blog post. STEPHANIE: Yeah. And then I think it turned into a Bike Shed episode, too [laughs]. JOËL: I think it did, yes. I think, in many ways, creativity begets creativity. It's hard to get started writing or producing content or whatever, but once you do, every idea you have kind of spawns new ideas. And then, pretty soon, you have a backlog that you can't go through. STEPHANIE: That's awesome. Any other highlights from the conference you want to shout out? JOËL: I'd love to give a shout-out to a couple of talks that I went to, Aji Slater's talk on the Enigma machine as a German code machine from World War II and how we can sort of implement our own in Ruby and an exploration of object-oriented programming was fantastic. Aji is just a masterful storyteller. So, that was really great. And then Alan Ridlehoover's talk on dealing with flaky tests that one, I think, was particularly useful because I think it's one of the talks that is going to be immediately relevant on Monday morning for, like, every developer that was in that room and is going back to their regular day job. And they can immediately use all of those principles that Alan talked about to deal with the flaky tests in their test suite. And there's, in particular, at the end of his presentation, Alan has this summary slide. He kind of broke down flakiness across three different categories and then talked about different strategies for identifying and then fixing tests that were flaky because of those reasons. And he has this table where he sort of summarizes basically the entire talk. And I feel like that's the kind of thing that I'm going to save as a cheat sheet. And that can be, like, I'm going to link to this and share it all over because it's really useful. Alan has already put his slides up online. It's all linked to that particular slide in the show notes because I think that all of you would benefit from seeing that. The talks themselves are recorded, but they're not going to be out for a couple of weeks. I'm sure when they do, we're going to go through and watch some and probably comment on some of the talks as well. So, Stephanie, what is new in your world? STEPHANIE: Yeah. So, I'm celebrating wrapping up a client project after a nine-month engagement. JOËL: Whoa, that's a pretty long project. STEPHANIE: Yeah, that's definitely on the longer side for thoughtbot. And I'm, I don't know, just, like, feeling really excited for a change, feeling really, you know, proud of kind of, like, all of the work that we had done. You know, we had been working with this client for a long time and had been, you know, continuing to deliver value to them to want to keep working with us for that long. But I'm, yeah, just looking forward to a refresh. And I think that's one of my favorite things about consulting is that, you know, you can inject something new into your work life at a kind of regular cadence. And, at least for me, that's really important in reducing or, like, preventing the burnout. So, this time around, I kind of started to notice, and other people, too, like my manager, that I was maybe losing a bit of steam on this client project because I had been working on it for so long. And part of, you know, what success at thoughtbot means is that, like, we as employees are also feeling fulfilled, right? And, you know, what are the different ways that we can try to make sure that that remains the case? And kind of rotating folks on different projects and kind of making sure that things do feel fresh and exciting is really important. And so, I feel very grateful that other people were able to point that out for me, too, when I wasn't even fully realizing it. You know, I had people checking in on me and being like, "Hey, like, you've been on this for a while now. Kind of what I've been hearing is that, like, maybe you do need something new." I'm just excited to get that change. JOËL: How do you find the balance between sort of feeling fulfilled and maybe, you know, finding that point where maybe you're feeling you're running out of steam–versus, you know, some projects are really complex, take a while to ramp up; you want to feel productive; you want to feel like you have contributed in a significant way to a project? How do you navigate that balance? STEPHANIE: Yeah. So, the flip side is, like, I also don't think I would enjoy having to be changing projects all the time like every couple of months. That maybe is a little too much for me because I do like to...on our team, Boost, we embed on our team. We get to know our teammates. We are, like, building relationships with them, and supporting them, and teaching them. And all of that is really also fulfilling for me, but you can't really do that as much if you're on more shorter-term engagements. And then all of that, like, becomes worthwhile once you're kind of in that, like, maybe four or five six month period where you're like, you've finally gotten your groove. And you're like, I'm contributing. I know how this team works. I can start to see patterns or, like, maybe opportunities or gaps. And that is all really cool, and I think also another part of what I really like about being on Boost. But yeah, I think what I...that losing steam feeling, I started to identify, like, I didn't have as much energy or excitement to push forward change. When you kind of get a little bit too comfortable or start to get that feeling of, well, these things are the way they are [laughs], -- JOËL: Right. Right. STEPHANIE: I've now identified that that is kind of, like, a signal, right? JOËL: Maybe time for a new project. STEPHANIE: Right. Like starting to feel a little bit less motivated or, like, less excited to push myself and push the team a little bit in areas that it needs to be pushed. And so, that might be a good time for someone else at thoughtbot to, like, rotate in or maybe kind of close the chapter on what we've been able to do for a client. JOËL: It's hard to be at 100% all the time and sort of always have that motivation to push things to the max, and yeah, variety definitely helps with that. How do you feel about finding signals that maybe you need a break, maybe not from the project but just in general? The idea of taking PTO or having kind of a rest day. STEPHANIE: Oh yeah. I, this year, have tried out taking time off but not going anywhere just, like, being at home but being on vacation. And that was really great because then it was kind of, like, less about, like, oh, I want to take this trip in this time of year to this place and more like, oh, I need some rest or, like, I just need a little break. And that can be at home, right? Maybe during the day, I'm able to do stuff that I keep putting off or trying out new things that I just can't seem to find the time to do [chuckles] during my normal work schedule. So, that has been fun. JOËL: I think, yeah, sometimes, for me, I will sort of hit that moment where I feel like I don't have the ability to give 100%. And sometimes that can be a signal to be like, hey, have you taken any time off recently? Maybe you should schedule something. Because being able to refresh, even short-term, can sort of give an extra boost of energy in a way where...maybe it's not time for a rotation yet, but just taking a little bit of a break in there can sort of, I guess, extend the time where I feel like I'm contributing at the level that I want to be. STEPHANIE: Yeah. And I actually want to point out that a lot of that can also be, like, investing in your life outside of work, too, so that you can come to work with a different approach. I've mentioned the month that I spent in the Hudson Valley in New York and, like, when I was there, I felt, like, so different. I was, you know, just, like, so much more excited about all the, like, novel things that I was experiencing that I could show up to work and be like, oh yeah, like, I'm feeling good today. So, I have all this, you know, energy to bring to the tasks that I have at work. And yeah, so even though it wasn't necessarily time off, it was investing in other things in my life that then brought that refresh at work, even though nothing at work really changed [laughs]. JOËL: I think there's something to be said for the sort of energy boost you get from novelty and change, and some of that you get it from maybe rotating to a different project. But like you were saying, you can change your environment, and that can happen as well. And, you know, sometimes it's going halfway across the country to live in a place for a month. I sometimes do that in a smaller way by saying, oh, I'm going to work this morning from a coffee shop or something like that. And just say, look, by changing the environment, I can maybe get some focus or some energy that I wouldn't have if I were just doing same old, same old. STEPHANIE: Yeah, that's a good point. So, one particularly surprising refresh that I experienced in offboarding from my client work is coming back to my thoughtbot, like, internal company laptop, which had been sitting gathering dust [laughs] a little bit because I had a client-issued laptop that I was working in most of the time. And yeah, I didn't realize how different it would feel. I had, you know, gotten everything set up on my, you know, my thoughtbot computer just the way that I liked it, stuff that I'd never kind of bothered to set up on my other client-issued laptop. And then I came back to it, and then it ended up being a little bit surprising. I was like, oh, the icons are smaller on this [laughs] computer than the other computer. But it definitely did feel like returning to home, I think, instead of, like, being a guest in someone else's house that you haven't quite, like, put all your clothes in the closet or in the drawers. You're still maybe, like, living out of a suitcase a little bit [laughs]. So yeah, I was kind of very excited to be in my own space on my computer again. JOËL: I love the metaphor of coming home, and yeah, being in your own space, sleeping in your own bed. There's definitely some of that that I feel, I think, when I come back to my thoughtbot laptop as well. Do you feel like you get a different sense of connection with the rest of our thoughtbot colleagues when you're working on the thoughtbot-issued laptop versus a client-issued one? STEPHANIE: Yeah. Even though on my client-issued computer I had the thoughtbot Slack, like, open on there so I could be checking in, I wasn't necessarily in, like, other thoughtbot digital spaces as much, right? So, our, like, project management tools and our, like, internal company web app, those were things that I was on less of naturally because, like, the majority of my work was client work, and I was all in their digital spaces. But coming back and checking in on, like, all the GitHub discussions that have been happening while I haven't had enough time to catch up on them, just realizing that things were happening [laughs] even when I was doing something else, that is both cool and also like, oh wow, like, kind of sad that I [chuckles] missed out on some of this as it was going on. JOËL: That's pretty similar to my experience. For me, it almost feels a little bit like the difference between back when we used to be in person because thoughtbot is now fully remote. I would go, usually, depending on the client, maybe a couple of days a week working from their offices if they had an office. Versus some clients, they would come to our office, and we would work all week out of the thoughtbot offices, particularly if it was like a startup founder or something, and they might not already have office space. And that difference and feeling the connection that I would have from the rest of the thoughtbot team if I were, let's say, four days a week out of a client office versus two or four days a week out of the thoughtbot office feels kind of similar to what it's like working on a client-issued laptop versus on a thoughtbot-issued one. STEPHANIE: Another thing that I guess I forgot about or, like, wasn't expecting to do was all the cleanup, just the updating of things on my laptop as I kind of had it been sitting. And it reminded me to, I guess, extend that, like, coming home metaphor a little bit more. In the game Animal Crossing, if you haven't played the game in a while because it tracks, like, real-time, so it knows if you haven't, you know, played the game in a few months, when you wake up in your home, there's a bunch of cockroaches running around [laughs], and you have to go and chase and, like, squash them to clean it up. JOËL: Oh no. STEPHANIE: And it kind of felt like that opening my computer. I was like, oh, like, my, like, you know, OS is out of date. My browsers are out of date. I decided to get an internal company project running in my local development again, and I had to update so many things, you know, like, install the new Ruby version that the app had, you know, been upgraded to and upgrade, like, OpenSSL and all of that stuff on my machine to, yeah, get the app running again. And like I mentioned earlier, just the idea of like, oh yeah, this has evolved and changed, like, without me [laughs] was just, you know, interesting to see. And catching myself up to speed on that was not trivial work. So yeah, like, all that maintenance stuff still got to do it. It's, like, the digital cleanup, right? JOËL: Exactly. So, you mentioned that on the client machine, you still had the thoughtbot Slack. So, you were able to keep up at least some messages there on one device. I'm curious about the experience, maybe going the other way. How much does thoughtbot stuff bleed into your personal devices, if at all? STEPHANIE: Barely. I am very strict about that, I think. I used to have Slack on my phone, I don't know, just, like, in an earlier time in my career. But now I have it a rule to keep it off. I think the only thing that I have is my calendar, so no email either. Like, that is something that I, like, don't like to check on my personal time. Yeah, so it really just is calendar just in case I'm, like, out in the morning and need to be, like, oh, when is my first meeting? But [laughs] I will say that the one kind of silly thing is that I also refuse to sign into my Google account for work. So, I just have the calendar, like, added to my personal calendar but all the events are private. So, I can't actually see what the events are [laughs]. I just know that I have something going on at, like, 10:00 a.m. So, I got to make sure I'm back home by then [laughs], which is not so ideal. But at the risk of being signed in and having other things bleed into my personal devices, I'm just living with that for now [laughs]. JOËL: What I'm hearing is that I could put some mystery events on your calendar, and you would have a fun surprise in the morning because you wouldn't know what it is. STEPHANIE: Yeah, that is true [laughs]. If you put, like, a meeting at, like, 8:00 a.m., [laughs] then I'm like, oh no, what's this? And then I arrive, and it's just, like [laughs], a fun prank meeting. So, you know, you were talking about how you were at the conference this week. And I'm wondering, how connected were you to work life? JOËL: Uh, not very. I tried to be very present in the moment at the conference. So, I'm, you know, connected to all the other thoughtboters who were there and connecting with the attendees. I do have Slack on my phone, so if I do need to check it for something. There was a little bit of communication that was going on for different things regarding the conference, so I did check in for that. But otherwise, I tried to really stay focused on the in-person things that are happening. I'm not doing any client work during those days that I'm at RubyConf, and so I don't need to deal with anything there. I had my thoughtbot laptop with me because that's what I used to give my presentation. But once the presentation was done, I closed that laptop and didn't open it again, and, honestly, that felt kind of good. STEPHANIE: Yeah, that is really nice. I'm the same way, where I try to be pretty connected at conferences, and, like, I will actually redownload Slack sometimes just for, like, coordinating purposes with other folks who are there. But I think I make it pretty clear that I'm, like, away. You know, like, I'm not actually...like, even though I'm on work time, I'm not doing any other work besides just being present there. JOËL: So, you mentioned the idea of work time. Do you have, like, a pretty strict boundary between personal time and work time and, like, try not to allow either to bleed into each other? STEPHANIE: Yeah. I can't remember if I've mentioned this on the show. I think I have, but I'm going to again because one of my favorite things that I picked up from The Bike Shed back when Chris Toomey and Steph Viccari were hosting the show is Chris had, like, a little ritual that he would do every day to signal that he was done with work. He would close his laptop and say, "Schedule shutdown complete," I think. And I've started adopting it because then it helps me be like, I'm not going to reopen my laptop after this because I have said the words. And even if I think of something that I maybe need to add to my to-do list, I will, instead of opening my computer and adding to my, like, whatever digital to-do list, I will, like, write it down on a piece of paper instead for the sake of, you know, not risking getting sucked back into, you know, whatever might be going on after the time that I've, like, decided that I need to be done. JOËL: So, you have a very strict divisioning between work time and personal time. STEPHANIE: Yeah, I would say so. I think it's important for me because even when I take time off, you know, sometimes folks might work a half day or something, right? I really struggle with having even a half day feel like, once I'm done with work, having that feel like okay, like, now I'm back in my personal time. I'd much prefer not working the entire day at all because that is kind of the only way that I can feel like I've totally reclaimed that time. Otherwise, it's like, once I start thinking about work stuff, it's like I need a mental boundary, right? Because if I'm thinking about a work problem, or, like, an interaction or, like, just anything, it's frustrating because it doesn't feel like time in my own brain [laughs] is my own. What do work and personal time boundaries look like for you? JOËL: I think it's evolved over time. Device usage is definitely a little bit more blurry for me. One thing that I have started doing since we've gone fully remote as the pandemic has been winding down and, you know, you can do things, but we're still working from home, is that more days than not, I work from home during the day, and then I leave my home during the evening. I do a variety of social activities. And because I like to be sort of present in the moment, that means that by being physically gone, I have totally disconnected because I'm not checking emails or anything like that. Even though I do have thoughtbot email on my phone, Gmail allows me to like log into my personal account and my thoughtbot account. I have to, like, switch between the two accounts, and so, that's, like, more work than I would want. I don't have any notifications come in for the thoughtbot account. So, unless I'm, like, really wanting to see if a particular email I'm waiting for has come in, I don't even look at it, ever. It's mostly just there in case I need to see something. And then, by being focused in the moment doing social things with other people, I don't find too much of a temptation to, like, let work life bleed into personal life. So, there's a bit of a physical disconnect that ends up happening by moving out of the space I work in into leaving my home. STEPHANIE: Yeah. And I'm sure it's different for everyone. As you were saying that, I was reminded of a funny meme that I saw a long time ago. I don't think I could find it if I tried to search for it. But basically, it's this guy who is, you know, sitting on one side of the couch, clearly working. And he's kind of hunched over and, like, typing and looking very serious. And then he, like, closes his laptop, moves over, like, just slides to the other side of the couch, opens his laptop. And then you see him, like, lay back, like, legs up on the coffee table. And it's, like, work computer, personal computer, but it's the same computer [laughs]. It's just the, like, how you've decided like, oh, it's time for, you know, legs up, Netflix watching [laughs]. JOËL: Yeah. Yeah. I'm curious: do you use your thoughtbot computer for any personal things? Or is it just you shut that down; you do the closing ritual, and then you do things on a separate device? STEPHANIE: Yeah, I do things on a separate device. I think the only thing there might be some overlap for are, like, career-related extracurriculars or just, like, development stuff that I'm interested in doing, like, separate from what I am paid to do. But that, you know, kind of overlaps a little bit because of, like, the tools and the stuff I have installed on my computer. And, you know, with our investment time, too, that ends up having a bit of a crossover. JOËL: I think I'm similar in that I'll tend to do development things on my thoughtbot machine, even though they're not necessarily thoughtbot-related, although they could be things that might slot into something like investment time. STEPHANIE: Yeah, yeah. And it's because you have all your stuff set up for it. Like, you're not [laughs] trying to install the latest Ruby version on two different machines, probably [laughs]. JOËL: Yeah. Also, my personal device is a Windows machine. And I've not wanted to bother learning how to set that up or use the Windows Subsystem for Linux or any of those tools, which, you know, may be good professional learning activities. But that's not where I've decided to invest my time. STEPHANIE: That makes sense. I had an interesting conversation with someone else today, actually, about devices because I had mentioned that, you know, sometimes I still need to incorporate my personal devices into work stuff, especially, like, two-factor authentication. And specifically on my last client project...I have a very old iPhone [laughs]. I need to start out by saying it's an iPhone 8 that I've had for, like, six or seven years. And so, it's old. Like, one time I went to the Apple store, and I was like, "Oh, I'm looking for a screen protector for this." And they're like, "Oh, it's an iPhone 8. Yikes." [laughs] This was, you know, like, not too long ago [laughs]. And the multi-factor authentication policy for my client was that, you know, we had to use this specific app. And it also had, like, security checks. Like, there's a security policy that it needed to be updated to the latest iOS. So, even if I personally didn't want to update my iOS [laughs], I felt compelled to because, otherwise, I would be locked out of the things that I needed to do at work [laughs]. JOËL: Yeah, that can be a challenge sometimes when you're adding work things to personal devices, maybe not because it's convenient and you want to, but because you don't have a choice for things like two-factor auth. STEPHANIE: Yeah, yeah. And then the person I was talking to actually suggested something I hadn't even thought about, which is like, "Oh, you know, if you really can't make it work, then, like, consider having that company issue another device for you to do the things that they're, like, requiring of you." And I hadn't even thought of that, so... And I'm not quite at the point where I'm like, everything has to be, like, completely separate [laughs], including two-factor auth. But, I don't know, something to consider, like, maybe that might be a place I get to if I'm feeling like I really want to keep those boundaries strict. JOËL: And I think it's interesting because, you know, when you think of the kind of work that we do, it's like, oh, we work with computers, but there are so many subfields within it. And device management and, just maybe, corporate IT, in general, is a whole subfield that is separate and almost a little bit alien. Two, I feel like me, as a software developer, I'm just aware of a little bit...like, I've read a couple of articles around...and this was, you know, years ago when the trend was starting called Bring Your Own Device. So, people who want to say, "Hey, I want to use my phone. I want to have my work email on my phone." But then does that mean that potentially you're leaking company memos and things? So, how do you secure that kind of thing? And everything that IT had to think through in order to allow that, the pros and cons. So, I think we're just kind of, as users of that system, touching the surface of it. But there's a lot of thought and discussion that, as an industry, the kind of corporate IT folks have gone through to struggle with how to balance a lot of those things. STEPHANIE: Yeah, yeah. I bet there's a lot of complexity or nuance there. I mean, we're just talking about, like, ways that we do or don't mix work and personal life. And for that kind of work, you know, that's, like, the job is to think really thoroughly about how people use their devices and what should and shouldn't be permissible. The last thing that I wanted to kind of ask about in terms of device management or, like, work and personal intermixing is the idea of being on call and your device being a way for work to reach you and that being a requirement, right? I feel very lucky to obviously not really be in that position. As consultants, like, we're not usually so embedded into a team that we're then brought into, like, an on-call rotation, and I think that's good for me. Like, I don't think that that is something I'd be interested in doing anytime soon. Do you have any experience with that? JOËL: I have not been on a project where I've had to be on call, and I think that's generally true for most of us at thoughtbot who are doing software development. I know those who are doing more kind of platformy SRE-type things are on call. And, in fact, we have specifically hired people in different regions around the world so that we can provide 24-hour coverage for that kind of thing. STEPHANIE: Yeah. And I imagine kind of like what we're talking about with work device management looks even different for that kind of role, where maybe you do need a lot more access to things, like, wherever you might be. JOËL: And maybe the answer there is you get issued a work-specific device and a work phone or something like that, or an old-school work pager. STEPHANIE: [laughs] JOËL: PagerDuty is not just a metaphoric thing. Back in the day, they used actual pagers. STEPHANIE: Yeah, that would be very funny. JOËL: So yeah, I can't speak to it from personal experience, but I could imagine that maybe some of the dynamics there might be a little bit different. And, you know, for some people, maybe it's fine to just have an app on your phone that pings you when something happens, and you have to be on call. And you're able to be present while waiting, like, in case you get pinged, but also let it go while you're on call. I can imagine that's, like, a really weird kind of, like, shadow, like, working, not working experience that I can't really speak to because I have not been in that position. STEPHANIE: Yeah. As you were saying that, I also had the thought that, like, our ability to step away from work and our devices is also very much dependent on, like, a company culture and those types of factors, right? Where, you know, it is okay for me to not be able to look at that stuff and just come back to it Monday morning, and I am very grateful [laughs] for that. Because I recognize that, like, not everyone is in that position where there might be a lot more pressure or urgency to be on top of that. But right now, for this time in my life, like, that's kind of how I like to work. JOËL: I think it kind of sits at the intersection of a few different things, right? There's sort of where you are personally. It might be a combination, like, personality and maybe, like, mental health, things like that, how you respond to how sharp or blurry those lines between work and personal life can be. Like you said, it's also an element of company culture. If there's a company culture that's really pushing to get into your personal life, maybe you need firmer boundaries. And then, finally, what we spent most of this episode talking about: technical solutions, whether that's, like, physically separating everything such that there are two devices. And you close down your laptop, and you're done for the day. And whether or not you allow any apps on your personal phone to carry with you after you leave for the day. So, I think at the intersection of those three is sort of how you're going to experience that, and every person is going to be a little bit different. Because those three...I guess I'm thinking of a Venn diagram. Those three circles are going to be different for everyone. STEPHANIE: Yeah, that makes complete sense. JOËL: On that note, shall we wrap up? STEPHANIE: Let's wrap up. Show notes for this episode can be found at bikeshed.fm. JOËL: This show has been produced and edited by Mandy Moore. STEPHANIE: If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter. STEPHANIE: Or reach both of us at hosts@bikeshed.fm via email. JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week. ALL: Byeeeeeee!!!!!! AD: Did you know thoughtbot has a referral program? If you introduce us to someone looking for a design or development partner, we will compensate you if they decide to work with us. More info on our website at: tbot.io/referral. Or you can email us at: referrals@thoughtbot.com with any questions.

Stephanie interviews Edward Loveall, a former thoughtbotter, now software developer at Relevant Healthcare. Part of their discussion centers around Edward's blog post on the tech industry's over-reliance on GitHub. He argues for the importance of exploring alternatives to avoid dependency on a single platform and encourages readers to make informed technological choices. The conversation broadens to include how to form opinions on technology, the balance between personal preferences and team decisions, and the importance of empathy and nuance in professional interactions. Both Stephanie and Edward highlight the value of considering various perspectives and tools in software development, advocating for a flexible, open-minded approach to technology and problem-solving in the tech industry. Relevant (https://relevant.healthcare/) Let's make sure Github doesn't become the only option (https://blog.edwardloveall.com/lets-make-sure-github-doesnt-become-the-only-option) And not but (https://blog.edwardloveall.com/and-not-but) Empathy Online (https://thoughtbot.com/blog/empathy-online) Transcript: STEPHANIE: Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Stephanie Minn. And today, I'm joined by a very special guest, a friend of the pod and former thoughtboter, Edward Loveall. EDWARD: Hello, thanks for having me. STEPHANIE: Edward, would you share a little bit about yourself and what you're doing these days? EDWARD: Yes, I am a software developer at a company called Relevant Healthcare. We do a lot of things, but the maybe high-level summary is we take very complicated medical data and help federally-funded health centers actually understand that data and help their population's health, which is really fun and really great. STEPHANIE: Awesome. So, Edward, what is new in your world? EDWARD: Let's see, this weekend...I live in a dense city. I live in Cambridge, Massachusetts, and it's pretty dense there. And a lot of houses are very tightly packed. And delivery drivers struggle to find the numbers on the houses sometimes because A, they're old and B, there is many of them. And so, we put up house numbers because I live in, like, a three-story kind of building, but there are two different addresses in the same three stories, which is very weird. And so [laughs], delivery drivers are like, "Where is number 10 or 15?" or whatever. And so, there's two different numbers. And so, we finally put up numbers after living here for, like, four years [chuckles]. So, now, hopefully, delivery drivers in the holiday busy season will be able to find our house [laughs]. STEPHANIE: That's great. Yeah, I have kind of a similar problem where, a lot of the times, delivery folks will think that my house is the big building next door. And the worst is those at the building next door they drop off their packages inside the little, like, entryway that is locked for people who don't live there. And so, I will see my package in the window and, you know, it has my name on it. It has, like, my address on it. And [laughs] some strategies that I've used is leaving a note on the door [laughter] that is, like, "Please redeliver my package over there," and, like, I'll draw an arrow to the direction of my house. Or sometimes I've been that person to just, like, buzz random [laughter] units and just hope that they, like, let me in, and then I'll grab my package. And, you know, if I know the neighbors, I'll, like, try to apologize the next time I see them. But sometimes I'll just be like, I just need to get my package [laughs]. EDWARD: You're writing documentation for those people working out in the streets. STEPHANIE: Yeah. But I'm glad you got that sorted. EDWARD: Yeah. What about you? What's new in your world? STEPHANIE: Well, I wanted to talk a little bit about a thing that you and I have been doing lately that I have been enjoying a lot. First of all, are you familiar with the group chat trend these days? Do you know what I'm talking about? EDWARD: No. STEPHANIE: Okay. It's basically this idea that, like, everyone is just connecting with their friends via a group chat now as opposed to social media. But as a person who is not a big group chat person, I can't, like, keep up with [chuckles], like, chatting with multiple people [laughter] at once. I much prefer, like, one-on-one interaction. And, like, a month ago, I asked you if you would be willing to try having a shared note, like, a shared iOS note that we have for items that we want to discuss with each other but, you know, the next time we either talk on the phone or, I don't know, things that are, like, less urgent than a text message would communicate but, like, stuff that we don't want to forget. EDWARD: Yeah. You're, like, putting a little message in my inbox and vice versa. And yeah, we get to just kind of, whenever we want, respond to it, or think about it, or use it as a topic for a conversation later. STEPHANIE: Yeah. And I think it is kind of a playbook from, like, a one-on-one with a manager. I know that that's, like, a strategy that some folks use. But I think it works well in the context of our friendship because it's just gotten, like, richer over time. You know, maybe in the beginning, we're like, oh, like, I don't know, here are some random things that I've thought about. But now we're having, like, whole discussions in the note [laughter]. Like, we will respond to each other, like, with sub-bullets [laughs]. And then we end up not even needing to talk about it on the phone because we've already had a whole conversation about it in the note. EDWARD: Which is good because neither of us are particularly brief when talking on the phone. And [laughs] we only dedicate, like, half an hour every two weeks. It sort of helps clear the decks a little. STEPHANIE: Yeah, yeah. So, that's what I recommend. Try a shared note for [laughs] your next friendship hangout. EDWARD: Yeah, it's great. I heartily recommend it. STEPHANIE: So, one of the things that we end up talking about a lot is various things that we've been reading about tech on the web [laughs]. And we share with each other a lot of, like, blog posts, or articles, various links, and recently, something of yours kind of resurfaced. You wrote a blog post about GitHub a little while ago about how, you know, as an industry, we should make sure that GitHub doesn't become our only option. EDWARD: Yeah, this was a post I wrote, I think, back in May, or at least earlier this year, and it got a bunch of traction. And it's a somewhat, I would say, controversial article or take. GitHub just had their developer conference, and it resurfaced again. And I don't have a habit of writing particularly controversial articles, I don't think. Most of my writing history has been technical posts like tutorials. Like, I wrote a whole tutorial on how to write SQL, or I did write one about how to communicate online. But I wasn't, like, so much responding to, like, a particular person's communication or a company's communication. And this is the first big post I've written that has been a lot more very heavily opinionated, very, like, targeted at a particular thing or entity, I guess you'd say. It's been received well, I think, mostly, and I'm proud of it. But it's a different little world for me, and it's a little scary, honestly. STEPHANIE: Yeah, I hear that, having an opinion [laughs], a very strong and maybe, like, a less popular opinion, and publishing that for the world. Could you recap what the thesis of it is for our listeners? EDWARD: Yeah, and I think you did a great job of it, too. I see GitHub or really any singular piece of technology that we have in...I'll say our stack with air quotes, but it's, you know, all the tools that we use and all the things that we use. It's a risk if you only have one of those things, let's say GitHub. Like, if the only way you know how to contribute to a code repository with, you know, 17 people all committing to that repository, if the only way you know how to do that is a pull request and GitHub goes away, and you don't have pull requests anymore, how are you going to contribute to code? It's not that you couldn't figure it out, or there aren't multiple ways or even other pull request equivalents on other sites. But it is a risk to rely on one company to provide all of the things that you potentially need, or even many of the things that you potentially need, without any alternatives. So, I wanted to try to lay out A: those risks, and B: encourage people to try alternatives, to say that GitHub is not necessarily bad, although they may not actually fit what you need for various reasons, or someone else for various reasons. But you should have an alternative in your back pocket so that in case something changes, or you get locked out, or they go away, or they decide to cancel that feature, or any number of other scenarios, you have greatly diminished that risk. So, that's the main thrust of the post. STEPHANIE: Yeah, I really appreciated it because, you know, I think a lot of us probably take GitHub for granted [laughs]. And, you know, every new thing that they kind of add to the platform is like, oh, like, cool, like, I can now do this. In the post, you kind of lay out all of the different features that GitHub has rolled out over the last, you know, couple of years. And when you see it all like that, you know, like, in addition to being, like, a code repository, you now have, like, GitHub Actions for CI/CD, you know, you can deploy static pages with it. It now has, like, an in-browser editor, and then, you know, Copilot, which, like, the more things that they [laughs] roll out, the more it's becoming, like, the one-stop shop, right? That, like, do all of your work here. And I appreciated kind of, like, seeing that and being like, oh, like, is this what I want? EDWARD: Right. Yeah, exactly. Yeah. And you mentioned a bunch. There's also issues and discussions. You mentioned their in-browser editor. But so many people use VS Code, which, while it was technically made by Microsoft, it's based on Electron, which was developed at GitHub. And GitHub even, like, took away their other Electron-based editor, Atom. And then now officially recommends VS Code. And everything from deploying all the way down to, like, thinking about and prioritizing features and editing the code and all of that pretty much could happen on GitHub. I think maybe the only thing they don't currently do is host non-static sites, maybe [laughs]. That's maybe about it. And who knows? Maybe they're working on that; as far as I know, they are, so... STEPHANIE: Yeah, absolutely. You also mentioned one thing that I really liked about the content in the post was that you talked about alternatives to GitHub, even, like, alternatives to all of the different features that we mentioned. I guess I'm wondering, like, what were you hoping that a reader from your blog post, like, what they would get out of reading and, like, what they would take away from kind of sharing your opinion? EDWARD: I wanted to try to meet people where I think they might be because I think a lot of people do use GitHub, and they do take it for granted. And they do sort of see it as this thing that they must use, or they want to use even, and that's fine. That's not necessarily a bad thing. I want them to see those alternatives and have at least some idea that there is something else out there, that GitHub doesn't become just not only the default, but, like, the only thing. I mean, to just [chuckles] re-paraphrase the title of the post, I want to make sure GitHub does not become the only option, right? I want people to realize that there are other options out there and be encouraged to try them. And I have found, for me, at least, the better way to do that is not to only focus on, like, hey, don't use GitHub. Like, I hope people did not come away with only that message or even that message at all. But that it is more, hey, maybe try something else out and to encourage you to try something out. I'm going to A: share the risks with you and B: give you some actual things to try. So, I talk about the things I'm using and some other platforms and different paradigms to think about and use. So, I hope they take those. We'll see what happens in the next, you know, months or years. And I'll probably never know if it was actually just from me or from many other conversations, and thoughts, and articles, and all that kind of stuff. But that's what it takes, so... STEPHANIE: Yeah. I think the other fun thing about kind of the, like, meta-conversation we're having about having an opinion and, like, sharing it with the world is that you don't even really say like, "This is better than GitHub," or, like, kind of make a statement about, like, you shouldn't use...you don't even say, "You shouldn't use GitHub," right? The message is, like, here are some options: try it out, and, like, decide for yourself. EDWARD: Yeah, exactly. I want to empower people to do that. I don't think it would have been useful if I'd just go and say, "Hey, don't do this." It's very frustrating to me to see posts that are only negatives. And, honestly, I've probably written those posts, like, I'm not above them necessarily. But I have found that trying to help people do what you want them to do, as silly and maybe obvious as that sounds, is a more effective way to get them to do what you want them to do [laughs], as opposed to say, "Hey, stop doing the thing I don't want you to do," or attack their identity, or their job, or some other aspect of their life. Human behavior does not respond well to that generally, at least in my experience. Like, having your identity tied up in a tool or a platform is, unfortunately, pretty common in, like, a tech space. Like, oh, like, Ruby on Rails is the best piece of software or something like that. And it's like, well, you might like it, and that might be the best thing for you. And personally, I really like Ruby on Rails. I think it does a great job of what it does. But as an example, I would not use Ruby on Rails to maybe build an iOS app. I could; I think that's possible, but I don't think that's maybe the best tool for that job. And so, trying to, again, meet people where they are. STEPHANIE: I guess it kind of goes back to what you're saying. It's like, you want to help people do what they are trying to do. EDWARD: Yeah. Maybe there's a little paternalistic thinking, too, of, like, what's good for the industry, even if it feels bad for you right now. I don't love that sort of paternalistic thinking. But if it's a real risk, it seems worth at least addressing or pointing out and letting people make that decision for themselves. STEPHANIE: Yeah, absolutely. I am actually kind of curious about how do you, like, decide something for yourself? You know, like, how do you form your own opinion about technology? I think, yeah, like, a lot of people take GitHub for granted. They use it because that's just what's used, and that may or may not be a good reason for doing so. But that was a position I was in for a long time, right? You know, especially when you're newer to the industry, you're like, oh, well, this is what the company uses, or this is what, like, the industry uses. But, like, how do you start to figure out for yourself, like, do I actually like this? Does this help me meet my goals and needs? Is it doing what I want it to be doing? Do you have any thoughts about that? EDWARD: Yeah. I imagine most people listening to this have tried lots of different pieces of software and found them great, or terrible, or somewhere in between. And I don't think there's necessarily one way to do this. But I think my way has been to try lots of things, unsurprisingly, and evaluate them based on the thing that I'm trying to do. Sometimes I'll go into a new field, or a new area, or a new product, or whatever, and you just sort of use what's there, or what people have told you about, or what you heard about last, and that's fine. That's a great place to start, right? And then you start seeing maybe where it falls down, or where it is frustrating or doesn't quite meet those needs. And it takes a bit of stepping back. Again, I don't think I'm, like, going to blow anyone's mind here by this amazing secretive technique that I have for, like, discovering good software. But it's, like, sitting there and going through this iterative loop of try it, evaluate it. Be honest with, is it meeting or not meeting some particular needs? And then try something else. Or now you have a little more info to arm yourself to get to the next piece that is potentially good. As you go on in your career and you've tried many, many, many pieces of things, you start to see patterns, right? And you know, like, oh, it's not like, oh, this is how I make websites. It's like, ah, I understand that websites are made with a combination of HTML, and CSS, and JavaScript and sometimes use frameworks. And there's a database layer with an ORM. And you start to understand all the different parts. And now that you have those keywords and those pieces a little more under your control or you have more experience with them, you can use all that experience to then seek out particular pieces. I'm looking for an ORM that's built with Rust because that's the thing I need to do it for; that's the platform I need to work with. And I needed to make sure that it supports MySQL and Postgres, right? Like, it's a very targeted thing that you wouldn't know when you're starting out. But over years of experience, you understand the difference and the reasons why you might need something like that. And sometimes it's about kind of evaluating options and maybe making little test projects to play around with those things or side projects. That's why something like investment time or 20% time is so helpful and useful for that if you're the kind of person who, you know, enjoys programming on your own in your own free time like I am. And that's also a great time to do it, although it's certainly not required. And so, that's kind of how I go through and evaluate whatever tool it is that I need. For something maybe more professional or higher stakes, there's a little more evaluation upfront, right? You want to make sure you make the right choice before you spend thousands of hours using it and potentially regretting [laughs] it and having to roll it back, causing even more thousands of hours of time. So, there's obviously some scrutiny there. But, again, that also takes experience and understanding the kind of need that you have. So, yeah, it's kind of a trade-off of, like, your time, and your energy, and your experience, and your interest. You will have many different inputs from colleagues, from websites, from posts on the internet, from Twitter, or fediverse-type kind of blogging and everything in between, right? So, you take all that in, and you try a bunch of stuff, and you come out on the other side, and then you do it again. STEPHANIE: Yeah, it sounds like you really like to just experiment, and I think that's really great. And I actually have to say that I am not someone who likes to do that [laughs]. Like, it's not where I focus a lot of my time. And it's why I'm, like, glad I'm friends with you, first of all. EDWARD: [laughs] STEPHANIE: But also, I've realized I'm much more of, like, a gatherer in terms of information and opinions. Like, I like hearing about other people's experience to then, like, help inform an opinion that I might develop myself. And, you know, it's not to say that, like, I am, like, oh yeah, like, so and so said this, and so, therefore, yeah, I completely believe what they have to say. But as someone who does not particularly want to spend a ton of my time trying out things, it is really helpful to know people who do like to do that, know people who I do trust, right? And then kind of like you had mentioned, just, like, having all these different inputs. And one thing that has changed for me with more experience is, previously, a lot of, like, the basis of what I thought was the quote, unquote, "right way" to develop software was, like, asking, like, other people and, you know, their opinions becoming my own. And, you know, at some point, though, that, like, has shifted, right? Where it's like, oh, like, you know, I remember learning this from so and so, and, like, actually, I think I disagree now. Or maybe it's like, I will take one part of it and be like, yeah, I really like test-driven development in this particular way that I have figured out how I do it, but it is different still from, like, who I learned it from. And even though, like, that was kind of what I thought previously as, like, oh yeah, like, this is the way that I've adopted without room for adjustment. I think that has been a growth, I guess, that I can point to and be like, oh yeah, like, I once was in a position where maybe opinions weren't necessarily my own. But now I spend a lot more time thinking about, like, oh, like, how do I feel about this? And I think there is, like, some amount of self-reflection required, right? A lot, honestly. Like, you try things, and then you think about, like, did I like that? [laughs] One without the other doesn't necessarily fully informed opinion make. EDWARD: Yeah, absolutely. I mean, I'm really glad you brought up that, like, you've heard an opinion, or a suggestion, or an idea from somebody, and you kind of adopt it as your own for a little bit. I like to think of it as trying on ideas like you try on clothing. Or something like, let me try on this jacket. Does this fit? And maybe you like it a little bit. Or maybe you look ridiculous, and it's [laughs] not quite for you. And you don't feel like it's for you. But you have to try. You have to, like, actually do it. And that is a completely valid way to, like, kick-starting some of those opinions, getting input from friends or colleagues, or just the world around you. And, like, hearing those things and trying them is 100% valid. And I'm glad you mentioned that because if I mentioned it, I think I kind of skipped over it or went through it very quickly. So, absolutely. And you're talking about how you just take, like, one part of it maybe. That nuance, that is, I think, really critical to that whole thought, too. Everything works differently for different people. And every tool is good for other, like, different jobs. Like, it will be like saying a hammer is the best tool, and it's, like, well, it's a good tool for the right thing. But, like, I wouldn't use a hammer to, like, I don't know, level the new house numbers I put on my house, right? But I might use them to, like, hit the nail to get them in. So, it's a silly analogy, but, like, there is always nuance and different ways to apply these different tools and opinions. STEPHANIE: I like that analogy. I think it would be really funny if there was someone out there who claimed that the hammer is the best tool ever invented [laughs]. EDWARD: Oh, I'm sure. I'm sure there is, you know. I'm not going to use a drill to paint my house, though [laughs]. STEPHANIE: That's a fair point, and you don't have to [chuckles]. EDWARD: Thank you [laughs]. STEPHANIE: But, I guess, to extend this thought further, I completely and wholeheartedly agree that, like, yeah, everyone gets to decide for themselves what works for them. But also, we work in relation with others. And I'm very interested in the balance of having your own ideas and opinions about tooling, software practices, like, whatever, and then how to bring that back into, like, working on a team or, like, working with others. EDWARD: Yeah. Well, I don't know if this is exactly what you're asking, but it makes me think of: you've gone off; you've discovered a whole bunch of stuff that you think works really well for you. And then you go to work, or you go to a community that is using a very different way of working, or different tools, or different technologies. That can be a piece of friction sometimes of, like, "Oh my gosh, I love Ruby on Rails. It's the best." And someone else is like, "I really, really don't like Ruby on Rails for reasons XYZ. And we don't use it here." And that can be really tough and, honestly, sometimes even disheartening, depending on how strongly you feel about that tool and how strongly they feel about their tools. And as a young developer many years ago, I definitely had a lot more of my identity wrapped up in the tools and technologies that I used. And that has been very useful to try to separate those two. I don't claim to be perfect at it or done with that work yet. But the more I can step away and say, you know, like, this is only a tool. It is not the tool. It is not the best tool. It is a tool that can be very effective at certain things. And I've found, at least right now, the more useful thing is to get to the root of the problem you're trying to solve and make sure you agree with everybody on that premise. So, yes, you may have come from a world where fast iteration and a really fluent language interface like Ruby has and a really fast iteration cycle like Rails has, is, like, the most important need to be solved because other things have been solved. You understand what you're doing for your product, or maybe you need to iterate quickly on that product. You've figured out an audience. You're getting payroll. You're meeting all that as a business. But then you go into a business that's potentially, like, let's say, much less funded. Or they have their market fit, and now they're working on, like, extreme performance optimization, or they're working on getting, like, government compliance, or something like that. And maybe Rails is still great. This is maybe a...the analogy may fall apart here. But let's pretend it isn't for some reason. You have to agree that, hey, like, yes, we've solved problem X that Rails really helps you solve. And now we're moving on to problem Y, and Rails may not help you solve that, or whatever technology you're using may not help you solve that. And I've found it to be much more useful to stop worrying about the means, and the tools, the things in between, and worry about the ends, worry about the goal, worry about the problems you're actually trying to solve. And then you can feel really invested in trying to solve that problem together as a group, as a team, as a community. I've found that to be very helpful. And I would also like to say it is extremely difficult to let some of that stuff go. It takes a lot of work. I see you nodding along. Like, it's really, really hard. And, like I said, I'm not totally done with it either. But that's, I think, it's something I'm really working on now and something I feel really strongly about. STEPHANIE: Yeah. You mentioned the friction of, like, working in an environment where there are different opinions, which is, you know, I don't know, just, like, reality, I guess [laughs]. EDWARD: Human nature. STEPHANIE: Yeah, exactly. And one thing I was thinking about recently was, like, okay, like, so someone else maybe made a decision about using a type of technology or, like, made a decision about architecture before my time or, like, above me, or whatever, right? Like, I wasn't there, and that is okay. But also, like, how do I maintain what I believe in and hold fast to, like, my opinions based on my value system, at least, without complaining? [laughs] Because I've only seen that a little bit before, right? When it just becomes, like, venting, right? It's like, ugh, like, you know, I have seen people who are coming from maybe, like, microservices or more of a JavaScript world, and they're like, ugh, like, what is going on with Rails? Like, this sucks [laughs]. And one thing I've been trying lately is just, like, communicating when I don't agree that something's a great idea. But also, like, acknowledging that, like, yeah, but this is how it is for this team, and I'm also not in a position to change it. Or, like, I don't feel so strongly about it that I'm like, "Hey, we should totally rethink using this, like, background job [laughs] platform." But I will be like, "Hey, like, I don't like this particular thing about it. And, you know, maybe here are some things that I did to mitigate whatever thing I'm not super into," or, like, "If I had more time, this is what I would do," and just putting it out there. Sometimes, I don't get, like, engagement on it. But it's a good practice for me to be, like, this is how I can still have opinions about things, even if I'm not, at least in this particular moment, in a position to change anything. EDWARD: It sounds to me like you in, at least at the lowest level, like, you want to be acknowledged, and you want to, like, be heard. You want to be part of a process. And yes, it doesn't always go with Stephanie's initial thought, or even final thought, or Edward's final thought. But it is very helpful to know that you are heard and you are respected. And it isn't someone just, like, completely disregarding any feeling that you have. As much as we like to say programming is this very, like, I don't know, value neutral, zero emotion kind of job, like, there's tons of emotion in this job. We want to do good things for the world. We want our technology to serve the people, ultimately, at least I do, and I know you do. But we sometimes disagree on the way to do that. And so, you want to make sure you're heard. And if you can't get that at work, like, and I know you do this, but I would encourage anyone listening out there to, like, get a buddy that you can vent to or get somebody that you can express, and they will hear you. That is so valuable just as a release, in some ways, to kind of get through what you need to get through sometimes. Because it is a job, and you aren't always the person that's going to make the decisions. And, honestly, like, you do still have one decision left, which is you can go work somewhere else if it really is that bad. And, like, it's useful to know that you are staying where you are because you appreciate the trade-offs that you have: a steady paycheck, or the colleagues that you work with, or whatever. And that's fine. That's an okay trade-off. And at some point, you might want to make a different trade-off, and that's also fine. We're getting real managery and real here. But I think it's useful. Like you said, this can be a very emotional career, and it's worth acknowledging that. STEPHANIE: Yeah, you just, you know, raised a bunch of, like, very excellent points. Yeah, at the end of the day, like, you know, you can do your best to, like, propose changes or, like, introduce new tooling and, like, see how other people feel about it. But, like, yeah, if you fundamentally do not enjoy working with a critical tool that, you know, a lot of the foundation of the work that you're doing day to day is built off of, then maybe there is a place where, like, another company that's using tools that you do feel excited or, like, passionate or, like, are a better alignment with what you hope to be doing. Kind of just going back to that theme that we were talking about earlier, like, everyone gets to decide for themselves, right? Like, the tools to help them do what they want to be doing. EDWARD: And you could even, like, reframe it for yourself, where instead of it being about the tools, maybe it's about the problem. Like, you start being more invested in, like, the problem that you're solving and, okay, maybe you don't want to use microservices or whatever, but, like, maybe you can get behind that if you realign yourself. The thing you're trying to solve is not the tool. The thing you're trying to solve is the problem. And that can be a useful, like, way to mitigate that or to, like, help yourself feel okay about the thing, whatever that is. STEPHANIE: Yeah. Now, how do I have this conversation with everyone [laughter] who claims on the internet that X is the solution to all their problems or the silver bullet, [laughs] or whatever? EDWARD: Yeah, that's tough because there are some very strong opinions on the internet, as I'm sure [laughs] you've observed. I don't know if I have the answer [laughs]. Once again, nuance and indecisions. I have been currently approaching it from kind of a meta-perspective of, like, if someone says, "X is the best tool," you know, "A hammer is the best tool," right? I'm not going to go write the post that's like, "No, hammer is, in fact, not the best tool. Don't use hammers." I would maybe instead write a post that's like, "Consider what makes the best tool." I've effectively, like, raised up one level of abstraction from, we're no longer talking about is X, or Y, or Z, the best tool? We're talking about how do we even decide that? How do we even think about that? One post...I'm now just promoting my blog posts, so get ready. But one thing I wrote was this post called And Not But. And I tried to make the case that instead of saying the word but in a sentence, so, like, yeah, yeah, we might want to use hammers, but we have to use drills or whatever. I'm trying to make the case that you can use and instead. So yeah, hammers are really good, and drills are really good in these other scenarios. And trying to get that nuance in there, like, really, really putting that in there and getting people to, like, feel that better, I think, has been really helpful, for me, certainly to get through. And part of the best thing about writing a blog post is just getting your own thoughts...I mean, it's another way to vent, right? It's getting your own thoughts out somewhere. And sometimes people respond to them. You'd be surprised who just reaches out and been like, "Hey, yeah, like, I really appreciated that post. That was really great." You weren't trying to reach that person, but now you have another connection. So, a side benefit for writing blog posts [inaudible 30:17] do it, or just even getting your thoughts out via a podcast, via a video, whatever. So, I've kind of addressed that. I also wrote a post when I worked at thoughtbot called Empathy Online. And that came out of, like, frustration with seeing people being too divisive or, in my opinion, unempathetic or inconsiderate. And instead of, again, trying to just say, "Stop it, don't do that," [laughs] but trying to, like, help use what I have learned when communicating in a medium that is kind of inherently difficult to get across emotion and empathy. And so, again, it's, in some ways, unsatisfying because what you really want to do is go talk to that person that says, "Hammer is the best tool," and say, "No, stop it [laughs]," and, like, slap them on the head or whatever, politely. But I think that probably will not get you very far. And so, if your goal, really, is to change the way people think about these things, I find it way more effective to, like, zoom out and talk about that on that sort of more meta-level and that higher level. STEPHANIE: Yeah. I liked how you called it, like, a higher level of abstraction. And, honestly, the other thing I was thinking about as you were talking about the, like, divisiveness that opinions can create, there's also some aspect of it, as a reader, realizing that one person sharing their opinion does not take away your ability to have a differing opinion [laughs]. And sometimes it's tough when someone's like, "Tailwind sucks [laughs], and it is a backward step in, you know, how we write CSS," or whatever. Yes, like, sometimes that can be kind of, like, inflammatory. But if you, like, kind of are translating it or, like, reading between the lines, they're just writing about their perspective from the things that they value. And it is okay for you to value different things and, for that reason, have a different perspective on the same thing. And, I don't know, that has helped me sometimes avoid getting into that, like, headspace of wanting to argue with someone [laughs] on the internet. Or they'll be like, "This is why I am right." [laughs] Now I have to write something and share it on the internet in response [laughs]. EDWARD: There's this idea of the narcissism of minor differences. And I believe the idea is this, like, you know, you're more likely to argue with someone who, like, 90% agrees with you. But you're just, like, quibbling over that last 10%. I mean, one might call it bikeshedding. I don't know if you've heard that phrase. But the thing that I have often found, too, is that, like the GitHub post, I will get people arguing with me, like, there's the kind of stuff I expected, where it's like, "Oh, but GitHub is really good," and XYZ and that's fine. And we can have that conversation. But it's kind of surprising, and I should have expected it, that people will sometimes be like, "Hey, you didn't go far enough. You should tell people to, like, completely delete their GitHub or, like, you know, go protest in the street." And, like, maybe that's true. I'm not saying it is or isn't. But I think one thing I try to think about is, in any post, in any trying convincing argument, like, you're potentially moving someone 1 step forward, even if there's ten steps to go. But they're never going to make those ten steps if they don't make the first 1. And so, you can kind of help them get there. And someone else's post can absolutely take them from step 5 to 6 or 6 to 7 or 7 to 8. And you won't accomplish it all at once, and it's kind of a silly thing to try, and your efforts are probably lost [laughs]. Unfortunately, it's a little bit of preaching to the choir because, like, yeah, the people that are going to respond to, like, the extreme, the end are, like, the people that already get it. And the people that you're trying to convince and move along are not going to get that thing. I do want to say that I could see this being perceived as, like, a very privileged position of, like, if there's some, like, genuine atrocity happening in the world, like, it is appropriate to go to extremes many times and sometimes, and that's fine, and people are allowed to be there. I don't want to invalidate that. It's a really tricky balance. And I'm trying to say that if your goal is to vent, that's fine. And if your goal is to move people from step 3 to 4, you have to meet people at step 3. And all that's valid and okay to try to help people move in that way. But it is very tricky. And I don't want to invalidate someone who's extremely frustrated because they're at step 10, and no one else is seeing the harm that not everybody else being at step 10 is. Like, that's an incredibly reasonable place to be and an okay place to be. STEPHANIE: Yeah, yeah. The other thing you just sparked, for me, is also the, like, power of, yeah, being able to say like, "Yeah, I agree with this 50%, or 60%, or, like, 90%." And also, there's this 10% that I'm like, oh, like, I wish were different, or I wish they'd gone further, or I wish they didn't say that. Or, you know, I just straight up disagree with this step 1 sentence, but the rest of the article, you know, I really related to. And, like, teasing that apart has been very useful for me, right? Because then I'm no longer like being like, oh, was this post good or bad? Do I agree with it or don't agree with it? It's like, there's room for [laughs] all of it. EDWARD: Yeah, that's that nuance that, you know, I liked this post, and I did not agree with these two parts of it, or whatever. It's so useful. STEPHANIE: Well, thanks, Edward, so much for coming on the show and bringing that nuance to this conversation. I feel really excited about kind of what we talked about, and hopefully, it resonates with some of our listeners. EDWARD: Yeah, I hope so too. I hope I can take them from step 2 to step 3 [laughs]. STEPHANIE: On that note, shall we wrap up? EDWARD: Let's wrap up. STEPHANIE: Show notes for this episode can be found at bikeshed.fm. JOËL: This show has been produced and edited by Mandy Moore. STEPHANIE: If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter. STEPHANIE: Or reach both of us at hosts@bikeshed.fm via email. JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week. ALL: Byeeeeeeeee!!!!!! AD: Did you know thoughtbot has a referral program? If you introduce us to someone looking for a design or development partner, we will compensate you if they decide to work with us. More info on our website at tbot.io/referral. Or you can email us at referrals@thoughtbot.com with any questions.

Joël got to do some pretty fancy single sign-on work. And when it came time to commit, he documented the ridiculous number of redirects to give people a sense of what was happening. Stephanie has been exploring Rails callbacks and Ruby debugging tools, using methods like save_callbacks and Kernel.caller, and creating a function call graph to better understand and manage complex code dependencies. Stephanie is also engaged in an independent project and seeking strategies to navigate the challenges of solo work. She and Joël explore how to find external support and combat isolation, consider ways to stimulate creativity, and obtain feedback on her work without a direct team. Additionally, they ponder succession planning to ensure project continuity after her involvement ends. They also reflect on the unique benefits of solo work, such as personal growth and flexibility. Stephanie's focus is on balancing the demands of working independently while maintaining a connected and sustainable professional approach. ASCII Sequence Diagram Creator (https://textart.io/sequence) Callback debugging methods (https://andycroll.com/ruby/find-list-debug-active-record-callbacks-in-the-console/) Kernel.caller (https://ruby-doc.org/core-3.0.2/Kernel.html#method-i-caller) Method.source_location (https://ruby-doc.org/core-3.0.2/Method.html#method-i-source_location) Building web apps by your lonesome by Jeremy Smith (https://www.youtube.com/watch?v=Rr871vmV4YM) Transcript: STEPHANIE: Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Stephanie Minn. JOËL: And I'm Joël Quenneville. And together, we're here to share a bit of what we've learned along the way. STEPHANIE: So, Joël, what's new in your world? JOËL: I got to do something really fun this week, where I was doing some pretty fancy single sign-on work. And when it came time to commit, I wanted to document the kind of ridiculous number of redirects that happen and give people a sense of what was going on. And for my own self, what I had been doing is, I had done a sequence diagram that sort of shows, like, three different services that are all talking to each other and where they redirect to each other as they all go through the sequence to sign someone in. And I was like, how could I embed that in the commit message? Because I think it would be really useful context for someone trying to get an overview of what this commit is doing. And the answer, for me, was, can I get this sequence diagram in ASCII form somewhere? And I found a website that allows me to do this in ASCII art. It's the textart.io/sequence. And that allows me to create a sequence diagram that gets generated as ASCII art. I can copy-paste that into a commit message. And now anybody else who is like, "What is it that Joël is trying to do here?" can look at that and be like, "Oh, oh okay, so, we got these, like, four different places that are all talking to each other in this order. Now I see what's happening." STEPHANIE: That's super neat. I love the idea of having it directly in your commit message just because, you know, you don't have to go and find a graph elsewhere if you want to understand what's going on. It's right there for you, for future commit explorers [laughs] trying to understand what was going on in this snippet of time. JOËL: I try as much as possible to include those sorts of things directly in the commit message because you never know who's reading the commit. They might not have access to some sort of linked resource. So, if I were like, "Hey, go to our wiki and see this link," like, sure, that would be helpful, but maybe the person reading it doesn't have access to the wiki. Maybe they do have access, but they're not on the internet right now, and so they don't have access to the wiki. Maybe the wiki no longer exists, and that's a dead link. So, as much as possible, I try to embed context directly in my commit messages. STEPHANIE: That's really cool. And just another shout out to ASCII art, you know [laughs], persevering through all the times with our fancy tools. It's still going strong [laughs]. JOËL: Something about text, right? STEPHANIE: Exactly. I actually also have a diagram graph thing to share about what's new in my world that is kind of in a similar vein. Another thoughtboter and former guest on the show, Sara Jackson, shared in our dev channel about this really cool mural graph that she made to figure out what was going on with callbacks because she was working on, you know, understanding the lifecycle of this model and was running into, like, a lot of complex behavior. And she linked to a really neat blog post by Andy Croll, too, that included a little snippet sharing a few callback debugging methods that are provided by ActiveRecord. So, basically, you can have your model and just call double underscore callbacks. And it returns a list of all the callbacks that are defined for that model, and I thought that was really neat. So, I played around with it and copypastad [laughs] the snippet into my Rails console to figure out what's going on with basically, like, the god object of that that I work in. And the first issue I ran into was that it was undefined because it turns out that my application was on an older [laughs] version of Rails than that method was provided on. But, there are more specific methods for the types of callbacks. So, if you are looking specifically for all the callbacks related to a save or a destroy, I think it's save underscore callbacks, right? And that was available on the Rails version I was on, which was, I think, 4. But that was a lot of fun to play around with. And then, I ended up chatting with Sara afterwards about her process for creating the diagram after, you know, getting a list of all these methods. And I actually really liked this hybrid approach she took where, you know, she automated some parts but then also manually, like, went through and stepped through the code and, like, annotated notes for the methods as she was traversing them. And, you know, sometimes I think about, like, wow, like, it would be so cool if this graph just generated automatically, but I also think there is some value to actually creating it yourself. And there's some amount of, like, mental processing that happens when you do that, as opposed to, like, looking at a thing that was just, you know, generated afterwards, I think. JOËL: Do you know what kind of graph Sara generated? Was it some kind of, like, function call graph, or was it some other way of visualizing the callbacks? STEPHANIE: I think it was a function call graph, essentially. It even kind of showed a lot of the dependencies, too, because some of the callback functions were quite complicated and then would call other classes. So, there was a lot of, I think, hidden dependencies there that were unexpected, you know, when you think you're just going to create a regular old [laughs] record. JOËL: Yeah, I've been burned by unexpected callbacks or callbacks that do things that you wouldn't want in a particular context and then creating bad data or firing off external services that you really didn't want, and that can be an unpleasant surprise. I appreciate it when the framework offers debugging tools and methods kind of built-in, so these helpers, which I was not aware of. It's really cool because they allow you to kind of introspect and understand the code that you're going through. Do you have any others like that from Rails or Ruby that you find yourself using from time to time to help better understand the code? STEPHANIE: I think one I discovered recently was Kernel.caller, which gives you the stack trace wherever you are when executing. And that was really helpful when you're not raising an exception in certain places, and you need to figure out the flow of the code. I think that was definitely a later discovery. And I'm glad to have it in my back pocket now as something I can use in any kind of Ruby code. JOËL: That can, yeah, definitely be a really useful context to have even just in, like, an interactive console. You're like, wait a minute, where's this coming from? What is the call stack right now? STEPHANIE: Do you have any debugging tools or methods that you like to use that maybe are under the radar a little bit? JOËL: One that I really appreciate that's built into Ruby is the source location method on the method object, so Ruby has a method object. And so, when you're dealing with some sort of method and, like, maybe it got generated programmatically through metaprogramming, or maybe it's coming from a gem or something like that, and you're just like, where is this define? I'm trying to find it. If you're in your editor and you're doing stuff, maybe you could run some sort of search, or maybe it has some sort of keyword lookup where you can just find the definition of what's under your cursor. But if you're in an interactive console, you can create a method object for that method name and then call dot source location on it. And it will tell you, here's where it's defined. So, very handy in the right circumstances. STEPHANIE: Awesome. That's a great tip. JOËL: Of course, one of the most effective debugging tools is having a pair, having somebody else work with you, but that's not always something that you have. And you and I were talking recently about what it's like to work solo on a project. Because you're currently on a project, you're solo, at least from the thoughtbot side of things. You're embedding with a team, with a client. Are you working on kind of, like, a solo subtask within that, or are you still kind of embedding and interacting with the other teammates on a regular basis? STEPHANIE: Yeah. So, the past couple of weeks, I am working on more of a solo initiative. The other members of my client team are kind of ramping up on some other projects for this next quarter. And since my engagement is ending soon, I'm kind of left working on some more residual tasks by myself. And this is new for me, actually. I've not really worked in a super siloed by-myself kind of way before. I usually have at least one other dev who I'm, like, kind of partnering up with on a project, or an epic, or something like that. And so, I've had a very quiet week where no one is, you know, kind of, like, reaching out to me and asking me to review their code, or kind of checking in, or, you know, asking me to check in with them. And yeah, it's just a little bit different than how I think I like to normally work. I do like to work with other people. So, this week has been interesting in terms of just kind of being a more different experience where I'm not as actively collaborating with others. JOËL: What do you think are some of the biggest challenges of being kind of a little bit out in your own world? STEPHANIE: I think the challenges for me can definitely be the isolation [laughs], and also, what kind of goes hand in hand with that is when you need help, you know, who can you turn to? There's not as much of an obvious person on your team to reach out to, especially if they're, like, involved with other work, right? And that can be kind of tough. Some of the other ones that I've been thinking about have been, you know, on one hand, like, I get to make all of the decisions that I want [laughs], but sometimes you kind of get, like, really in your own head about it. And you're not in that space of, like, evaluating different solutions that you maybe might not think of. And I've been trying to figure out how to, like, mitigate some of that risk. JOËL: What are some of the strategies that you use to try to balance, like making good decisions when you're a bit more solo? Do you try to pull in someone from another team to talk ideas through? Do you have some sort of internal framework that you use to try to figure out things on your own? What does that look like? STEPHANIE: Yeah, luckily, the feature I'm working on is not a huge project. Well, if it were, I think then I wouldn't be alone on it. But, you know, sometimes you find yourself kind of tasked with one big thing for a while, and you are responsible for from start to finish, like all of the architectural decisions to implementation. But, at least for me, the scope is a little more narrow. And so, I don't feel as much of a need to get a lot of heads together because I at least feel somewhat confident in what I'm doing [laughs]. But I have found myself being a bit more compelled to kind of just verbalize what I'm doing more frequently, even to, like, myself in Slack sometimes. It's just like, I don't know who's reading this, but I'm just going to put it out there because maybe someone will see this and jump in and say, "Oh, like, interesting. Here's some other context that I have that maybe might steer you away from that," or even validating what I have to say, right? Like, "That sounds like a good idea," or, you know, just giving me an emoji reaction [laughs] is sometimes all I need. So, either in Slack or when we give our daily sync updates, I am, I think, offering a little more details than I might if I already was working with someone who I was more in touch with in an organic way. JOËL: And I think that's really powerful because it benefits you. Sort of by having to verbalize that or type it out, you, you know, gain a little bit of self-awareness about what you're trying to do, what the struggles are. But also, it allows anybody else who has potentially helpful information to jump in. I think that's not my natural tendency. When I'm on something solo, I tend to kind of, like, zoom in and focus in on something and, like, ignore a little bit of the world around me. Like, that's almost the time when I should look at overcommunicating. So, I think most times I've been on something solo, I sort of keep relearning this lesson of, like, you know, it's really important to constantly be talking out about the things that you're doing so that other people who are in a broader orbit around you can jump in where necessary. STEPHANIE: Yeah, I think you actually kind of touched on one of the unexpected positives, at least for me. Something I wasn't expecting was how much time I would have to just be with my thoughts. You know, as I'm implementing or just in my head, I'm mulling over a problem. I have less frequent, not distractions necessarily, but interruptions. And sometimes, that has been a blessing because I am not in a spot where I have a lot of meetings right now. And so, I didn't realize how much generative thought happens when you are just kind of, like, doing your own thing for a little bit. I'm curious, for you, is that, like, a space that you enjoy being when you're working by yourself? And I guess, you know, you were saying that it's not your natural state to kind of, like, share what's going on until maybe you've fully formed an idea. JOËL: I think I often will regret not having shared out before everything is done. The times that I have done it, I've been like, that was a really positive experience; I should do that more. I think it's easy to sort of wait too long before sharing something out. And with so many things, it feels like there's only one more small task before it's done. Like, I just need to get this one test to go green, and then I can just put up a PR, and then we'll have a conversation about it. But then, oh, this other test broke, or this dependency isn't installing correctly. And before you know it, you've spent a whole day chasing down these things and still haven't talked. And so, I think if some of those things were discussed earlier, it would help both to help me feel more plugged in, but also, I think everybody else feels like they're getting a chance to participate as well. STEPHANIE: So, you mentioned, you know, obviously, there's, like, the time spent just arriving at the solution before sharing it out for feedback. But have you ever been in a position where there is no one to give you feedback and, like, not even a person to review your code? JOËL: That's really challenging. So, occasionally, if I'm working on a project, maybe it would be, like, very early-stage startup that maybe just has, like, a founder, and then I'm, like, the only technical person on the team, generally, what I'll try to do is to have some kind of review buddy within thoughtbot, so some other developer who's not staffed on my project but who has access to the code such that I can ask them to say, "Hey, can you just take a look at this and give me a code review?" That's the ideal situation. You know, some companies tend to lock things down a lot more if you're dealing with something like healthcare or something like that, where there might be some concerns around personal information, that kind of thing. But generally, in those cases, you can find somebody else within the company who will have some technical knowledge who can take a look at your code; at least, that's been my experience. STEPHANIE: Nice. I don't think I've quite been in that position before; again, I've really mostly worked within a team. But there was a conference talk I watched a little bit ago from Jeremy Smith, and it was called Building Web Apps by Your Lonesome. And he is a, like, one-man agency. And he talked about, you know, what it's like to be in that position where you pretty much don't have other people to collaborate with, to review your code. And one thing that he said that I really liked was shifting between writer and editor mode. If you are the person who has to kind of just decide when your code is good enough to merge, I like that transition between, like, okay, I just spent however many hours putting together the solution, and now I'm going to look at it with a critical eye. And sometimes I think that might require stepping away for a little bit or, like, revisiting it even the next day. That might be able to help see things that you weren't able to notice when you were in that writing mode. But I have found that distinction of roles really helpful because it does feel different when you're looking at it from those two lenses. JOËL: I've definitely done that for some, like, personal solo projects, where I'm participating in a game jam or something, and then I am the only person to review my code. And so, I will definitely, at that point, do a sort of, like, personal code review where I'll look at it. Maybe I'm doing PRs on GitHub, and I'm just merging. Maybe I'm just doing a git diff and looking at a commit in the command line on my own machine. But it is useful, even for myself, to sort of switch into that editor mode and just kind of look at everything there and say, "Is it in a good place?" Ideally, I think I do that before putting it out for a co-worker's review, so you kind of get both. But on a solo project, that has worked actually pretty well for me as well. STEPHANIE: One thing that you and I have talked about before in a different context, I think, when we have chatted about writing conference talks, is you are really great about focusing on the audience. And I was thinking about this in relation to working solo because even when you are working by yourself on a project, you're not writing the code for yourself, even though you might feel like [laughs] it in the moment. And I also kind of like the idea of asking, like, who are you building for? You know, can you ask the stakeholder or whoever has hired you, like, "Who will maintain this project in the future?" Because likely, it won't be you. Hopefully, it won't be you unless that's what you want to be doing. There's also what my friend coined the circus factor as opposed to the bus factor, which is, like, if you ran away to the circus tomorrow [laughs], you know, what is the impact that would have? And yeah, I think working solo, you know, some people might think, like, oh, that gives me free rein to just write the code exactly how I want to, how I want to read it. But I think there is something to be said about thinking about the future of who will be [inaudible 18:10] what you just happen to be working on right now. JOËL: And keep in mind that that person might be future you who might be coming back and be like, "What is going on here?" So, yeah, audience, I think, is a really important thing to keep in mind. I like to ask the question, if somebody else were looking at this code, and somebody else might be future me, what parts would they be confused by? If I was walking somebody else through the code for the first time, where would they kind of stop me through the walkthrough and be like, "Hey, why is this happening? What's the connection between these two things? I can see they're calling each other, but I don't know why." And that's where maybe you put in a comment. Maybe you find a better method or a class name to better explain what happens. Maybe you need to put more context in a commit message. There's all sorts of tools that we can use to better increase documentation. But having that pause and asking, "What will confuse someone?" is, I think, one of the more powerful techniques I do when I'm doing self-review. STEPHANIE: That's really cool. I'm glad you mentioned that, you know, it could also be future you. Because another thing that Jeremy says in this talk that I was just thinking about is the idea of optimizing for autonomy. And there's a lot to be said there because autonomy is like, yeah, like, you end up being the person who has to deal with problems [laughs], you know, if you run into something that you can't figure out, and, ideally, you'll have set yourself up for success. But I think working solo doesn't mean that you are in your own universe by yourself completely. And thinking about future, you, too, is kind of, like, part of the idea that the person in this moment writing code will change [laughs]. You'll get new information. Maybe, like, you'll find out about, like, who might be working on this in the future. And it is kind of a fine balance between making sure that you're set up to handle problems, but at the same time, maybe it's that, like, you set anyone up to be able to take it away from where you left it. JOËL: I want to take a few moments to sort of talk a little bit about what it means to be solo because I think there are sort of multiple different solo experiences that can be very different but also kind of converge on some similar themes. Maybe some of our listeners are listening to us talking and being like, "Well, I'm not at a consultancy, so this never happens to me." But you might find yourself in that position. And I think one that we mentioned was maybe you are embedded on a team, but you're kind of on a bit of a larger project where you're staffed solo. So, even though you are part of a larger team, you do feel like the initiative that you're on is siloed to you a little bit. Are there any others that you'd like to highlight? STEPHANIE: I think we also mentioned, you know, if you're a single developer working on an application because you might be the first technical hire, or a one-person agency, or something, that is different still, right? Because then your community is not even your company, but you have to kind of seek out external communities on social networks, or Slack groups, or whatever. I've also really been interested in the idea of developers kind of being able to be rotated with some kind of frequency where you don't end up being the one person who knows everything about a system and kind of becomes this dependency, right? But how can we make projects so, like, well functioning that, like, anyone can step in to do some work and then move on? If that's just for a couple of weeks, for a couple of months. Do you have any thoughts about working solo in that kind of situation where you're just stepping into something, maybe even to help someone out who's, you know, on vacation, or kind of had to take an unexpected leave? JOËL: Yeah, that can be challenging. And I think, ideally, as a team, if you want to make that easier, you have to set up some things both on a, like, social level and on a tactical level, so all the classic code quality things that you want in place, well structured, encapsulated code, good documentation, things like that. To a certain extent, even breaking down tasks into smaller sort of self-sufficient stories. I talk a lot about working incrementally. But it's a lot easier to say, "Hey, we've got this larger story. It was broken down into 20 smaller pieces that can all be shipped independently, and a colleague got three of them done and then had to go on leave for some reason. Can you step in and do stories 4 through 20?" As opposed to, "Hey, we have this big, amorphous story, and your colleague did some work, and it kind of is done. There's a branch with some code on it. They left a few notes or maybe sent us an email. But they had to go on leave unexpectedly. Can you figure it out and get it done?" The second scenario is going to be much more challenging. STEPHANIE: Yeah, I was just thinking about basically what you described, right? Where you might be working on your own, and you're like, well, I have this one ticket, and it's capturing everything, and I know all that's going on [laughs], even though it's not quite documented in the ticket. But it's, you know, maybe on my branch, or in my head, or, worst of all, on my local machine [laughs] without being pushed up. JOËL: I think maybe that's an anti-pattern of working solo, right? A lot of these disciplines that you build when you're working in a team, such as breaking up tickets into smaller pieces, it's easy to kind of get a little bit lazy with them when you're working solo and let your tickets inflate a little bit, or just have stuff thrown together in branches on your local machine, which then makes it harder if somebody does need to come in to either collaborate with you or take over from you if you ever need to step aside. STEPHANIE: Right. I have definitely seen some people, even just for their personal projects, use, like, a Trello board or some other project management tool. And I think that's really neat because then, you know, obviously, it's maybe just for their own, like, self-organization needs, but it's, like, that recognition that it's still a complicated project. And just because they're working by themselves doesn't mean that they can't utilize a tool for project management that is meant for teams or not even teams [laughs], you know, people use them for their own personal stuff all the time. But I really like that you can choose different levels of how much you're documenting for your future self or for anyone else. You had mentioned earlier kind of the difference between opening up a PR for you...you have to merge your branch into main or whatever versus just committing to main. And that distinction might seem, like, if you were just working on a personal project, like, oh, you know, why go through the extra step? But that can be really valuable in terms of just seeing, like, that history, right? JOËL: I think on solo projects, it can really depend on the way you tend to treat your commit history. I'm very careful with the history on the main branch where I want it to tell a sort of, like, cohesive story. Each commit is kind of, like, crafted a little bit. So, even when I'm working solo and I'm committing directly to master or to the main branch, I'm not just, like, throwing random things there. Ideally, every commit is green and builds and is, like, self-contained. If you don't have that discipline, then it might be particularly valuable to go through the, like, a branching system or a PR system. Or if you just want, like, a place to experiment, just throw a bunch of code together, a bunch of things break; nothing is cohesive, that's fine. It's all a work in progress until you finally get to your endpoint, and then you squash it down, or you merge it, or whatever your workflow is, and then it goes back into the main branch. So, I think that for myself, I have found that, oftentimes, I get not really a whole lot of extra value by going through a branching and PR system when it's, like, a truly solo project, you know, I'm building a side project, something like that. But that's not necessarily true for everyone. STEPHANIE: I think one thing I've seen in other people's solo projects is using a PR description and, you know, having the branching strategy, even just to jot down future improvements or future ideas that they might take with the work, especially if you haven't kind of, like, taken the next step of having that project management system that we talked about. But there is, like, a little more room for some extra context or to, like, leave yourself little notes that you might not want necessarily in your commit history but is maybe more related to this project being, like, a work in progress where it could go in a lot of different directions, and you're figuring that out by yourself. JOËL: Yeah, I mean, definitely something like a draft PR can be a great place to have work in progress and experiment and things like that. Something you were saying got me wondering what distinction you typically have between what you would put in a commit message versus something that you would put in a PR description, particularly given that if you've got, like, a single commit PR, GitHub will automatically make the commit message your PR message as well. STEPHANIE: This has actually evolved for me over time, where I used to be a lot more reliant on PR descriptions holding a lot of the context in terms of the decision-making. I think that was because I thought that, like, that was the most accessible place of information for reviewers to find out, you know, like, why certain decisions were made. And we were using, you know, PR templates and stuff like that. But now the team that I'm working on uses commit message templates that kind of contain the information I would have put in a PR, including, like, motivation for the change, any risks, even deployment steps. So, I have enjoyed that because I think it kind of shortens the feedback loop, too, right? You know, you might be committing more frequently but not, you know, opening a PR until later. And then you have to revisit your commits to figure out, like, okay, what did I do here? But if you are putting that thought as soon as you have to commit, that can save you a little bit of work down the line. What you said about GitHub just pulling your commit message into the PR description has been really nice because then I could just, like, open a thing [laughs]. And that has been nice. I think one aspect that I really like about the PR is leaving myself or reviewers, like, notes via comments, like, annotating things that should not necessarily live in a more permanent form. But maybe I will link to documentation for a method that I'm using that's a little less common or just add some more information about why I made this decision over another at a more granular level. JOËL: Yeah, I think that's probably one of the main things that I tend to put in a PR message rather than the commit message is any sort of extra information that will be helpful at review time. So, maybe it's a comment that says, "Hey, there is a lot of churn in this PR. You will probably have a better experience if you review this in split view versus unified view," things like that. So, kind of, like, meta comments about how you might want to approach reviewing this PR, as opposed to something that, let's say somebody is reviewing the history or is, like, browsing the code later, that wouldn't be relevant to them because they're not in a code review mindset. They're in a, like, code reading, code understanding mindset or looking at the message to say, "Why did you make the changes? I saw this weird method. Why did you introduce that?" So, hopefully, all of that context is in the commit message. STEPHANIE: Yeah, you reminded me of something else that I do, which is leave notes to my future self to revisit something if I'm like, oh, like, this was the first idea I had for the, you know, the way to solve this problem but, you know, note to self to look at this again tomorrow, just in case I have another idea or even to, like, you know, do some more research or ask someone about it and see if they have any other ideas for how to implement what I was aiming for. And I think that is the editor mode that we were talking about earlier that can be really valuable when you're working by yourself to spend a little extra time doing. You know, you are essentially optimizing for autonomy by being your own reviewer or your own critic in a healthy and positive way [laughs], hopefully. JOËL: Exactly. STEPHANIE: So, at the beginning of this episode, I mentioned that this is a new experience for me, and I'm not sure that I would love to do it all of the time. But I'm wondering, Joël, if there are any, you know, benefits or positives to working solo that you enjoy and find that you like to do just at least for a short or temporary amount of time. JOËL: I think one that I appreciate that's maybe a classic developer response is the heads downtime, the focus, being able to just sit down with a problem and a code editor and trying to figure it out. There are times where you really need to break out of that. You need somebody else to challenge you to get through a problem. But there are also just amazing times where you're in that flow state, and you're getting things done. And that can be really nice when you're solo. STEPHANIE: Yeah, I agree. I have been enjoying that, too. But I also definitely am looking forward to working with others on a team, so it's kind of fun having to get to experience both ways of operating. On that note, shall we wrap up? JOËL: Let's wrap up. STEPHANIE: Show notes for this episode can be found at bikeshed.fm. JOËL: This show has been produced and edited by Mandy Moore. STEPHANIE: If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter. STEPHANIE: Or reach both of us at hosts@bikeshed.fm via email. JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week. ALL: Byeeeeeeeeeeeee!!!!!! AD: Did you know thoughtbot has a referral program? If you introduce us to someone looking for a design or development partner, we will compensate you if they decide to work with us. More info on our website at tbot.io/referral. Or you can email us at referrals@thoughtbot.com with any questions.

Stephanie discovered a new book: The Staff Engineer's Path! Joël's got some D&D goodness. Together, they revisit a decade-old blog post initially published in 2013, which discussed the application of Sandi Metz's coding guidelines and whether these rules remain relevant and practiced among developers today. The Manager’s Path (https://www.goodreads.com/en/book/show/33369254) The Staff Engineer’s Path (https://www.goodreads.com/en/book/show/61058107) Not Another D&D Podcast (https://naddpod.com/) Sandi Metz rules for developers (https://thoughtbot.com/blog/sandi-metz-rules-for-developers) Bike Shed episode on heuristics (https://www.bikeshed.fm/398) In Relentless Pursuit of REST (https://www.youtube.com/watch?v=HctYHe-YjnE) Transcript: JOËL: Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Joël Quenneville. STEPHANIE: And I'm Stephanie Minn. And together, we're here to share a bit of what we've learned along the way. JOËL: So, Stephanie, what's new in your world? STEPHANIE: So, I picked up a new book from the library [laughs], which that in itself is not very new. That is [laughs] a common occurrence in my world. But it was kind of a fun coincidence that I was just walking around the aisles of what's new in nonfiction, and staring me right in the face was an O'Reilly book, The Staff Engineer's Path. And I think in the past, I've plugged The Manager's Path by Camille Fournier on the show. And in recent years, this one was published, and it's by Tanya Reilly. And it is kind of, like, the other half of a career path for software engineers moving up in seniority at those higher levels. And it has been a really interesting companion to The Manager's Path, which I had read even though I wasn't really sure I wanted to be manager [laughs]. And now I think I get that, like, accompaniment of like, okay, like, instead of walking that path, like, what does a staff plus engineer look like? And kind of learning a little bit more about that because I know it can be really vague or ambiguous or look very different at a lot of different companies. And that has been really helpful for me, kind of looking ahead a bit. I'm not too far into it yet. But I'm looking forward to reading more and bringing back some of those learnings to the show. JOËL: I feel like at the end of the year, Stephanie, you and I are probably going to have to sit down and talk through maybe your reading list for the year and, you know, maybe shout out some favorites. I think your reading list is probably significantly longer than mine. But you're constantly referencing cool books. I think that would probably be a fun, either end-of-year episode or a beginning-of-year episode for 2024. One thing that's really interesting, though, about the contrast of these two particular books you're talking about is how it really lines up with this, like, fork in the road that a lot of us have in our careers as we get more senior. You either move into more of a management role, which can be a pretty significant departure from what you have to do as a developer, or you kind of go into this, like, ultra-senior individual contributor path. But how that looks day to day can be very different from your sort of just traditional sitting down and banging out tickets. So, it's really cool there's two books looking at both of those paths. STEPHANIE: Yeah, absolutely. And I think the mission that they were going for with these books was to kind of illuminate a little bit more about that fork and that decision because, you know, it can be easy for people to maybe just default into one or the other based on what their organization wants for them without, like, fully knowing what that means. And the more senior you get, the more vague and, like, figure it out yourself [laughs] the work becomes. And it can be very daunting to kind of just be thrown into that and be like, well, I'm in this leadership position now. People are looking to me, and I have all this responsibility, but, like, what do I do? Yeah, so I'm kind of enjoying this book, that is...it's not a technical book, which is actually kind of what I like about it. It's actually more of a leadership book, which is really important for that kind of role. Even though, you know, they are still in that IC track, but it does come with a lot of leadership responsibility. JOËL: Yes, leadership in a very different way than management. But—and this may be counterintuitive for some people, especially earlier on in their careers—going further up that individual contributor track doesn't just mean getting more intense technically. It often means you've got to focus on things more like leadership, like being a bit more strategic, aligning technical initiatives with strategic goals. STEPHANIE: Yeah, and having a bigger impact and being a force multiplier, even in both the manager and, like, the staff plus role, like, that, you know, is the thing that ties the rising level. JOËL: Yeah, in many ways, maybe the individual contributor track is slightly misnamed because while, yes, you're not managing a sort of sub-organization within the company, it's still about being a force multiplier. STEPHANIE: Yeah, that's a really great point [laughs]. Maybe we'll be able to come up with a better [laughs] name for that. JOËL: I've mentioned several times on this podcast that I've been enjoying playing Dungeons & Dragons, D&D, with some friends and some colleagues. And something that was particularly fun that some friends and I did this summer is we hired a professional DM to run one shot for us. And that was just an absolutely lovely experience. Well, as a result of that, I am now subscribed to this guy's newsletter. And he'll do, like, various D&D events at different times. One thing that was really cool that I found out recently...as we're recording this, it's the week before election day in the U.S. And because a lot of voting happens in schools, typically, schools have the day off. And so, this guy sent out an email saying he was offering to run a, like, all day...effectively, a little mini-D&D camp for school-age kids on election day so that you can do your work. You can go vote, and you don't have to...basically, he'll watch your kids for you and, like, get them introduced to playing D&D, which I think is just a really cool thing to do. STEPHANIE: I love that. It's so heartwarming [laughs]. And it's such a great idea because, oftentimes, people are still working, and so they need childcare, like, on those kinds of days. And yeah, I think D&D is such a fun thing for kids to get into, too. You know, it requires so much, like, imagination, and I can imagine it's such a blast. JOËL: I got that email, and I was like, that is such a perfect idea. I love it so much. STEPHANIE: I wanted to plug my D&D recommendation. I'm pretty sure I have mentioned it on the show before. But there is a podcast that I listen to called Not Another D&D Podcast, which is, you know, a live play Dungeons & Dragons podcast campaign that's hosted by these comedians, formerly of CollegeHumor, and it's very fun. I always laugh. They have this, like, a kind of offshoot of the main show that they do called D&D Court, which is very fun. Because, as you were saying, like, you know, you hired a DM to run your game. And I know that...I'm sure lots of people have fun stories about their home games and, like, the drama that happens [laughs] with their friends. JOËL: Absolutely. Absolutely. STEPHANIE: And so, with D&D Court, listeners can write in with their drama or their conflicts and get an official ruling from the hosts about who was right [laughs] in the situation that they write in about. JOËL: So, you get to bring your best rules lawyering to the D&D Court. STEPHANIE: Yeah, exactly [laughs]. JOËL: That sounds kind of amazing. Recently, I had someone reach out to me asking about an older blog post that we'd written about the Sandi Metz Rules. This blog post was initially published in 2013, so ten years ago, and was talking about some guidelines that Sandi Metz at the time was talking about that she was using in some of her code. And we talked about how our experience was applying those to some of our work as well. And so, the question was, you know, ten years later, is that still something that thoughtbot developers like to follow in their code? We'll link to the article in the show notes. But I'll just read out the rules here real quick. So, there's four of them. The first one is a class can be no longer than 100 lines of code. The second is a method can be no longer than five lines of code. The third is pass no more than four parameters into a method, and hash options count, so no getting clever with those. And then, finally, controllers can only instantiate one object. You only get one instance variable. And views can only talk to that one instance variable. Had you or are you familiar with these rules? Is that something that you think about or use in your daily writing of code? STEPHANIE: Yeah. So, when you proposed this topic, I had to revisit these rules. And I can't recall if I had seen them before. They seemed familiar. And I've read, you know, a couple of Sandi Metz's books, so maybe those were places where she had mentioned them. But the one thing that really struck me when I was first reading the rules was how declarative they were in terms of, like, kind of just telling you what the results should be without really saying how. So, for example, the one where you said, you know, a method should not be more than five lines [laughs], I had the silly thought of, like, well, you could just, you know, stuff everything into a single line [laughs] and just completely disregard line limit if you wanted, and it would technically still follow the rule. JOËL: If they didn't want us to do that, they wouldn't give us semicolons in Ruby. STEPHANIE: Exactly [laughs]. So, that is kind of what struck me at first. Is that something you noticed? JOËL: I think what is interesting with them is that there's not always a ton of rationale given behind them. Our article talks a little bit about some of the why that might be helpful and how that might look like in practice. I'm not sure what Sandi's original...I don't know if it was one of her books or maybe on a...it might have been on a podcast appearance she talked about them, so she might go more in-depth there. But yeah, they are a little bit declarative. It's just like, hey, here's...it's almost basically the kind of thing that can be enforced by a linter, which is perhaps the point. STEPHANIE: Ooh, that's really interesting. It's like, on one hand, I like how simple they are, right? It's like, they're very obvious. If you're not following them, you can tell. But on the other hand, they seem to be more of a supplement to the gained knowledge and experience that you kind of get from knowing how to implement those rules. I think you and I will both agree that we don't want to stuff everything [laughs] into a single line with semicolons. But if someone who maybe is newer to development and is coming to these rules, I think they might be wondering, like, how do I do this? JOËL: Do you follow these rules in your own code? STEPHANIE: I think the ones that are easier to follow, for me, and that I think I've come to do more instinctually, are the rules about class line length and method line length just because I'm kind of looking out for opportunities to pull out a method or, you know, make sure that this class is just doing one thing. And if it's starting to seem to cover a couple of different responsibilities, I'm a little bit more on the lookout. But I do like these rules as like, you know, like, hey, once you hit, you know, 100 lines in a class, like, maybe that's your cue to start thinking about opportunities for extraction. JOËL: Do you sort of consciously follow these rules or have them maybe even encoded in a linter? Or is it more you're following other things, and somehow, it just lines up with these principles? STEPHANIE: I would say that, like, I'm not thinking about them very actively. But that could be a very interesting exercise, and I think, you know, that's what folks did in the blog post. They were like, hey, we took these rules, and we really kept them in mind as we were developing. But I think kind of what we were talking about earlier about, like, what we've learned or the strategies we've learned to implement kind of converge on these rules. And the rules actually are more of the result of other ideas or heuristics that we follow. JOËL: I mean, you dropped the keyword heuristics there. And I think that brings me back to an earlier episode we did where we talked about heuristics. And one of the things that came up on that episode was the idea that, oftentimes, we use heuristics as a way to sort of flatten a lot of experience and knowledge into sort of one, like, short rule, or short phrase, or something, one guideline, even though it's sort of trying to just summarize a mountain of wisdom. And so, oftentimes, you can look at something like these rules and be like, okay, well, what's the point? Or maybe you even just follow it to the letter without really thinking about the why behind it, and that can sometimes be problematic. And on the other hand, you might know all of the ideas that go behind them. And without necessarily knowing the rule itself, you just kind of happen to follow it because you're intimately familiar with all of these other software principles that converge on those same ideas. STEPHANIE: Yeah, agreed. I think that the more interesting ones to me are the no more than four method arguments and only one instance variable per controller. JOËL: Interesting. STEPHANIE: I'm curious if those are sparking anything for you [laughs]. JOËL: I think the no more than four method arguments, to me, is probably the least controversial. It's generally accepted that having many arguments to a method is a code smell. And there's a few different code smells that are related to that. There's forms of coupling incandescence; there are data clumps, things like that. I've often heard a sort of rule of three. And so, if you're going more than three, then you might want to revisit the structure of what you're building. Four is a bit of an arbitrary cut-off, I'll agree. Most of these are arbitrary cut-offs. But I think the idea to maybe keep your method to fewer arguments is generally a good thing to do. STEPHANIE: I liked that the rule points out that hash options account because I think that's maybe where people get a little more hand-wavy, or you have your ops hash [laughs] that can be just a catch-all for anything. You know, it's like, once you start putting stuff in there, I don't know, I feel like it's a like a law of the universe. It's like, oh, people will just stuff more things in there [laughs]. And it takes obviously more effort or, like, specific energy to, like, think through what those things might represent, or some alternative ways of handling those arguments. We definitely do have, I think, a couple of episodes on value objects. But that's something that we have talked a lot about before in terms of, you know, how can we take some kind of primitive data, hashes included, and turn them into a richer object that can then be passed on its own? JOËL: Right. And an options hash is generally...it's too much of a catch-all to really have an identity as its own sort of value object. It doesn't really represent any single thing. It's just everything else bag of data. One thing that's interesting that the article notes is that a lot of the helpers in Rails take a lot of arguments and that it is absolutely not worth trying to fight the framework to try to follow these rules. So, the article does take a very pragmatic approach, I think, to the idea of these rules. STEPHANIE: Yeah. And I think there is even a caveat to the rules where it's like, you can break them if you have a good reason, or if you're working with someone else and they give you the thumbs up [laughs], which I really like a lot because it almost kind of compels you to stop and be like, do I have a good reason of doing this? Just making sure, or I'll run it by a friend. And shifting that, I guess, that focus from kind of just coding from, like, your default mode of thinking to a more active one. JOËL: Right. There is a rule zero, which says you can break any of the other rules as long as you convince either your pair or your reviewer to give you a thumbs up on breaking the rule. So, you'd mentioned the fourth rule about a single instance variable in a controller kind of was one of the ones that stood out to you. What is particularly striking about that rule? STEPHANIE: I think this one is hard to follow, and I think the blog post mentions that as well. Because at least I've seen our web applications grow more and more complex. And it can be really challenging to just be like, what is this page doing? Like, what, you know, data does it need to know? And have that be the single thing. Because really, a lot of our web apps have a lot of things [laughs] that they're doing, and sometimes it feels like you have to capture more than one object or at least, like, a responsibility in this way. I think that's the one that I, you know, in my ideal world, I'm like, yeah, like, we have all these, like, perfectly RESTful routes. And, you know, we're only dealing with, you know, a single resource. But once you start to have some more complexity, I think that can be a little more challenging. JOËL: I think it's interesting that you mentioned RESTful routing because I think that is maybe one of the bigger things that does trigger having more instance variables in your controller actions. If you're following sort of the traditional Rails RESTful routes, every page is generally focused on a singular resource. Now, that may not necessarily line up with a table in your database, and that's fine. But you're dealing with a singular thing or perhaps, you know, in the case of an index page, a singular collection of things, which can be represented with a single instance variable. Once you start adding custom routes that may not be necessarily tied to a particular resource, now you can very easily kind of have a proliferation of all sorts of different things that interact with each other because you're no longer centered on a single thing. STEPHANIE: Yeah, that's true, which actually reminds me of something we've talked about before, too, when we were both reading Sustainable Rails. The author talks about custom routes and actually advocates for making all routes RESTful. And if you need a vanity URL or something like that, you can always alias it. That I liked, right? It's like, okay, even if, you know, your resource is not something that's like, ActiveRecord-backed, is there some abstraction or concept of a resource in there? And I actually did really like in the blog post in the example; that is one that I've used before, too. They were dealing with this idea of a dashboard, which I would, you know, say is pretty common in a lot of web applications these days. And it's funny because a dashboard can hold so much data, right? It's really, like, a composite of a lot of different things, you know, what is most, like, useful for the user to see in one place. But they were in the blog post. And this, again, this is kind of something that I've done before. They were able to capture that with the idea of, like, a dashboard as an object and that being codified using a presenter or a facade. JOËL: Right. So, instead of having a group, and a status, and a user, and all these, like, separate things that your page that you're showing is a sort of collection of all these different types of objects, you wrap them together in a dashboard object that's kind of a facade. And I guess that really does line up with the idea of RESTful routing because you're likely going to have a dashboard's controller show action that's showing the user's dashboard. So, it makes sense, you know, that show page is rendering a dashboard object. STEPHANIE: Can we talk a little bit about things not to do, or maybe things that might be a little more questionable [laughs], and if you've seen them and how you felt about them? JOËL: I think it is sometimes tricky to define your boundaries right in that sometimes you create a facade object that really is just...it doesn't really represent anything. It's just there to wrap around some other things. And sometimes that can be awkward. I think the dashboard works partly because it lines up so neatly with the sort of RESTful routing and thinking in terms of resources that you want to do at the controller layer. But drawing boundaries incorrectly or just trying to throw everything in some kind of grab bag object can...it's not a magic bullet, right? You've got to put some thought into the data modeling, even when you are pulling the facade pattern. STEPHANIE: Yeah, I think other things that I've seen before that could theoretically follow this rule maybe [laughs], you know, I'd love to hear your thoughts about it. When you start, you're like, oh, like, my controller action method does just, you know, set one instance variable. But it turns out that there's all these other instance variables that either through a hook or, like, in the parent controller or even in the view I've seen before, too [laughs]. And I'm just kind of curious if that kind of raises your eyebrow at all or if you've seen any good reasons for doing so. JOËL: I think setting instance variables in a view would absolutely cause me to raise an eyebrow. STEPHANIE: [laughs] Agreed. JOËL: Generally, don't put logic in the view. I think that we definitely have in parent controllers; we'll set other instance variables for things like maybe a current user, right? That's how we store that state. And I think that is totally fine to have around. Typically, we don't access that instance variable directly. We're referencing some kind of helper method. But yeah, I would not consider that a violation of the rule. I think another common one that might come up is when you have some kind of nested resource. And so, in your URL, you might have a nested resource where you're saying, "Oh, I'm looking at specifically this comment under this article or something like that." And then, you want to have access to both objects in the controller. So, I think that's a pretty common scenario where you might want to have both instance variables. Something that I'm thinking about...this is not a fully formed thought, so I'm curious about your opinions here. Is there an interesting distinction between variables in code that you want to use within a controller versus variables that you want to be accessible from a view? Because instance variables in a controller are kind of overloaded. They're a way of having state in a controller, but they're also a way of passing data into a view. And so, that sort of dual purpose there maybe causes them to be a little bit trickier to reason about than instance variables in a random Ruby object. What do you think? STEPHANIE: Yeah, I was actually having the same thought as you were going there, which is that it is kind of interesting that the view, you know, is that level of what you want to display to your user. But it can have access to, like, whatever you put in the controller [laughs], and that is...and, you know, in some ways, it's like, that connection needs to happen somewhere, right? And it's here. But I think that can definitely be abused sometimes, too. So, this, you know, fourth rule that we're talking about really has to do with a more traditional Rails app. But, again, with the complexity of web apps in 2023 [chuckles], you know, we also see Rails used just as an API a lot with a separate front-end framework. And your controller is rendering some JSON, which I think has that harder boundary between what is the data that the server is involved with and what we want to send to our client. And I'm curious if you have any thoughts about how this rule applies in that situation. JOËL: I think I tend to see not really any difference there. If I'm building an API, typically, I'm trying to do so in a pretty RESTful manner. Maybe I'm doing a GraphQL API, and things might be different for that. But for a traditional REST API, yeah, typically, you're fetching one resource or some sort of compound resource, in which case, you're representing that with a facade object. And yep, you can generally get away, I think, with a single instance variable with, you know, a few exceptions around maybe some extra context about maybe something like the current user, or a parent object, or something like that. I guess the view is really you're using a different mechanism for rendering JSON, and there are a bunch out there that the community uses. I think I don't really see a difference between rendering to HTML versus rendering to JSON, or XML, or whatever. How about you? STEPHANIE: That's a good point. I think I'm with you where the rule still applies. But I have also seen things get really loosey-goosey [laughs] when we decide we're rendering JSON, and now we're suddenly putting the instance variables into a hash along with other stuff. But what you said was interesting about, like, sometimes you do need that extra context, right? And, like, figuring out what the best way to package that requires a bit of, like, sustained thought, I think, because it can, you know, be really easy to be like, oh well, this is the one interface that I have to get data from the server. So, if I just sneak this in here [laughs], what's the matter? But yeah, I think, you know, that's probably why rules like this exist [laughs] to help provide some guardrails and make us think a little deeper about it. JOËL: I think sometimes, as a community, we maybe exaggerate the differences between, like, RESTful HTML view and a RESTful JSON API. I tend to think of them as more or less the same. We just have, you know, a different representation the V layer of our MVC framework. Everything else still kind of lines up. STEPHANIE: Yeah, that's a really good point. I actually hadn't thought about it that way. Because I think maybe I have been influenced by the world of GraphQL [laughs] a little bit, or it's kind of hard to have a foot in both worlds, where you maybe have to context switch a little bit about, like, the paradigms, and then you find them influencing you in different ways. Because I have seen sometimes, like, what maybe initially were meant to be traditional more, like, RESTful JSON APIs kind of start to turn into that, like, how do we get what we need from this endpoint? JOËL: I'm curious how you feel in general about the facade pattern. Is that something that you've used, something that you like? STEPHANIE: I think I would say that I don't actually reach for it, like, upfront, right? Usually, I'm still trying to maybe put some things in my models [laughs]. But I have used it before once; it kind of became clear that, like, a lot of the methods on the model had to do with more really server-side concerns. And I was, like, wanting to just pull out some presentational pieces. I think the hardest part with the facade pattern is naming. I have really struggled sometimes to think of, like, it's not quite the component that makes it up. So, what is it instead? JOËL: Right. Right. I think, for me, sometimes the naming goes the other way around in that I'll start more to kind of, like, routing our resource level and try to think about, okay, this particular view of the data that I want to have, or this particular operation that I want to do, what am I actually dealing with? What is the resource here? So, maybe I'm viewing a dashboard. Or maybe what I'm doing is creating or destroying a subscription, even though those are not necessarily tables in the database. And once I have that underlying concept, then I can start creating an object that represents that, which might be a combination of multiple ActiveRecord models that represent tables. STEPHANIE: Yeah. You're actually pointing out, like, a really great use case that we see a lot, I think, is when you start to have to reach for resources, you know, that are different ActiveRecord classes. And how do you combine them together to represent the idea that you want, you know, for your feature? JOËL: I think it's more of, like, an outside-facing perspective rather than an inside-facing perspective. So, instead of looking at, hey, these are the set of ActiveRecord classes I have because these are my database tables, how can I, like, tack on to them to make this operation work? I'll sort of start almost from, like, a zoomed-out perspective, blank slate to say, "Hey, this is the kind of operation that I'm trying to do. What sort of resource am I dealing with ideally?" And, you know, maybe the idea is, okay, I'm dealing with a dashboard. I'm trying to subscribe to something...a newsletter, so the idea is I'm creating a subscription. Then, from there, I can start looking at, okay, do I have the concept of a subscription in this application? Oh, I don't. There is no subscriptions table because that's not a thing that we track in our data mode. That's fine. But I probably need at least some kind of in-memory object to track the idea of a subscription, and then maybe from there, that grows. So, I'm kind of working from the problem towards the database rather than from the database out. STEPHANIE: Yeah, I like that a lot. The outside-in phrase that you used really triggered something for me, which is being product engineers, right? Like, having a seat at the table when the feature is in that, like, ideation phase, I think is also really important because that's where you really learn what that like, abstraction is at the user level. And also, it could be a really good place to give your input if the feature is being designed in a way that doesn't really support the, you know, kind of quality of code and, like, separation that you would like. That's the part that I'm still working on and still learning how to do. But sometimes, you know, it's, like, really critical to the job to, like, be in that room and be like, these designs; what are some places that we could extract it at that level even? And kind of, like, separate things out from there rather than having to deal with it [laughs] deep in your codebase. JOËL: I think what I'm really kind of hearing and emphasizing in what you just said is the importance of not just writing code but being involved in the product and how that really enriches you because you know the problem domain. And that allows you to then write the code that you need at the different levels of the app to best model the situation you're working with. So, we've kind of gone through all the rules and talked about them. I'm curious, though, for you, are these rules that you follow in your code? How closely do you adhere to this set of rules? Is this still something that's relevant to you in 2023 as much as it was to the authors of that blog post in 2013? STEPHANIE: I have to say they're not ones that I have thought about on a daily basis, but after this conversation, maybe they will be. And I am kind of excited to maybe, like, bring this up to other people on my team and be like, "What do you think about these rules?" Just, like, revisiting them as a group or just, like, having that conversation. Because I think that's, you know, where I am most interested in is, like, is wondering how other people incorporate them into their work and hearing different opinions from the team. And I think there's a lot of, like, generative discussion that ultimately leads to better code as a result. JOËL: I think for myself, I'm not following the rules directly. But a lot of my code ends up approximating those rules anyway because of other principles that I follow. So, in practice, while my code doesn't strictly follow those rules, it does look pretty close to that anyway. STEPHANIE: I almost think this could be a great, you know, discussion for your team, too, like, if any listeners want to...not quite a book club but kind of an article club, if you will [laughs], and see how other people on your team feel about it. Because I think that's kind of where there is, like, a really sweet spot in terms of learning and development. JOËL: On that note, shall we wrap up? STEPHANIE: Let's wrap up. Show notes for this episode can be found at bikeshed.fm. JOËL: This show has been produced and edited by Mandy Moore. STEPHANIE: If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter. STEPHANIE: Or reach both of us at hosts@bikeshed.fm via email. JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week. ALL: Byeeeeeee!!!!!!!! AD: Did you know thoughtbot has a referral program? If you introduce us to someone looking for a design or development partner, we will compensate you if they decide to work with us. More info on our website at tbot.io/referral. Or you can email us at referrals@thoughtbot.com with any questions.

Joël was selected to speak at RubyConf in San Diego! After spending a month testing out living in Upstate New York, Stephanie is back in Chicago. Stephanie reflects on a recent experience where she had to provide an estimate for a project, even though she didn't have enough information to do so accurately. In this episode, Stephanie and Joël explore the challenges of providing estimates, the importance of acknowledging uncertainty, and the need for clear communication and transparency when dealing with project timelines and scope. RubyConf 2023 (https://rubyconf.org/) How to estimate well (https://thoughtbot.com/blog/how-to-estimate-feature-development-time-maybe-don-t) XKCD hard problems (https://xkcd.com/1425/) Transcript: STEPHANIE: Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Stephanie Minn. JOËL: And I'm Joël Quenneville. And together, we're here to share a bit of what we've learned along the way. STEPHANIE: So, Joël, what's new in your world? JOËL: Big piece of news in my world: I recently got accepted to speak at RubyConf in San Diego next month in November. I'm really excited. I'm going to be talking about the concept of time and how that's actually multiple different things and the types of interactions that do and do not make sense when working with time. STEPHANIE: Yay. That's so exciting. Congratulations. I am very excited about this topic. I'm wondering, is this something that you've been thinking about doing for a while now, or was it just an idea that was sparked recently? JOËL: It's definitely a topic I've been thinking about for a long time. STEPHANIE: Time? [laughs] JOËL: Haha. STEPHANIE: Sorry, that was an easy one [laughs]. JOËL: The idea that we often use the English word time to refer to a bunch of, like, fundamentally different quantities and that, oftentimes, that can sort of blur into one another. So, the idea that a particular point in time might be different from a duration, might be different from a time of day, might be different to various other quantities that we refer to generically as time is something that's been in the back of my mind for quite a while. But I think turning that into a conference talk was a more recent idea. STEPHANIE: Yeah, I'm curious, I guess, like, what was it that made you feel like, oh, like, this would be beneficial for other people? Did everything just come together, and you're like, oh, I finally have figured out time [laughs]; now I have this very clear mental model of it that I want to share with the world? JOËL: I think it was sparked by a conversation I had with another member of the thoughtbot team. And it was just one of those where it's like, hey, I just had this really interesting conversation pulling on this idea that's been in the back of my mind for years. You know, it's conference season, and why not make that into a talk proposal? As often, you know, the best talk proposals are, at least for me, I don't always think ahead of time, oh, this would be a great topic. But then, all of a sudden, it comes up in a conversation with a colleague or a client, or it becomes really relevant in some work that I'm doing. It happens to be conference season, and like, oh, that's something I want to talk about now. STEPHANIE: Yeah, I like that a lot. I was just thinking about something I read recently. It was about creativity and art and how long a piece of work takes. And someone basically said it really just takes your whole life sometimes, right? It's like all of your experiences accumulated together that becomes whatever the body of work is. Like, all of that time spent maybe turning the idea in your head or just kind of, like, sitting with it or having those conversations, all the bugs you've probably encountered [laughs] involving date times, and all of that coalescing into something you want to create. JOËL: And you build this sort of big web of ideas, not all that makes sense to talk about in a conference talk. So, one of the classic sources of bugs when dealing with time are time zone and daylight savings. I've chosen not to include those as part of this talk. I think other people have talked about them. I think it's less interesting or less connected to the core idea that I have that, like, there are different types of time. Let's dig into what that means for us. So, I purposefully left that out. But there's definitely a lot that could be said for those. STEPHANIE: Awesome. Well, I really look forward to watching your talk when it is released to the public. JOËL: So, our listeners won't be able to tell, but we're on a video call right now. And I can see from your background that you are back at home in Chicago. It's been a few weeks since we've recorded together. And, in the last episode we did, you were trying out living somewhere in Upstate New York. How was that experience? And what has the transition back to Chicago been for you? STEPHANIE: Yeah, thanks for asking. I was in Upstate New York for the whole month of September. And then I took the last two weeks off of work to, you know, just really enjoy being there and make sure I got to do everything that I wanted to do out there before I came home to, you know, figure out, like, is this a place where I want to move? And yeah, this is my first, like, real full week back at work, back at home. And I have to say it's kind of bittersweet. I think we really enjoyed our time out there, my partner and I. And coming back home, especially, you know, when you're in a stage of life where you're wanting to make a change, it can be a little tough to be like, uh, okay, like, now I have to go back [laughs] to what my life was like before. But we've been very intentional about trying to bring back some of the things that we enjoyed being out there, like, back into just our regular day-to-day lives. So, over the weekend, we were making sure that we wanted to spend some time in nature because that's something that we were able to do a lot of during our time in New York. And, yeah, I think just bringing a bit of that, like, vacation energy into day-to-day life so the grind of kind of work doesn't become too much. JOËL: Anything in particular that you've tried to bring back from that experience to your daily life in Chicago? STEPHANIE: Yeah. I think, you know, when you're in a new place, everything is very exciting and, like, novel. Before work or, like, during my breaks, I would go out into the world and take a little walk and, like, look at the houses on the street that I was staying at. Or there's just a sense of wonder, I suppose, where everywhere you look, you're like, oh, like, this is all new. And I felt very, like, present when I was doing that. And over time, when you've been somewhere for a long time, you lose a little bit of that sense of, like, willingness to be open to new things, or just, like, yeah, that sense of like, oh, like, curiosity, because you feel like you know somewhere and, like, you kind of start to expect oh, like, this street will be exactly like how I've walked a million times [laughs]. But trying to look around a little more, right? Like, be a little aware and be like, oh, like, Halloween is coming around the corner. And so, enjoying that as, like, the thing that I notice around me, even if I am still on the same block, you know, in my same neighborhood, and, yeah, wanting to really appreciate, like, my time here before we leave. Like, I don't want to just spend it kind of waiting for the next thing to happen. Because I'm sure there will also be a time where I miss [laughs] Chicago here once we do decide to move. JOËL: I don't know about you, but I feel like a sense of change, even if it is cyclical, is really helpful for me to kind of maintain a little bit of that wonder, even though I've lived in one place for a decade. So, I live in New England in the Northeast U.S. We have pretty marked seasons that change. And so, seeing that happen, you know, kind of a warm summer, and now we're transitioning into fall, and the weather is getting colder. The trees are turning all these colors. So, there's always kind of within, like, a few weeks or a few months something to look forward to, something that's changing. Life never feels stagnant, even though it is cyclical. And I don't know if that's been a similar experience for you. STEPHANIE: Yeah, I like that a lot because I think one of the issues around feeling kind of stuck here in Chicago was that things were starting to feel stagnant, right? Like, we're wanting to make a big change in our life. That's still on the table, and that's still our plan. But noticing change, even when you think like, ugh, like, this again? [laughs] I think that could really shift your perspective a little bit or at least change how you feel about being somewhere. And that's definitely what I'm trying to do, kind of even when I am in a place of, like, waiting to figure out what the next step is. Speaking of change, I had a recent lesson learned or, I suppose, a story to share with you about a new insight or perspective I had about how I show up at work that I'd like to share. JOËL: What is this new perspective? STEPHANIE: Well, I guess, [chuckles], first of all, I'm curious to get your reaction on this. Have you ever heard anyone tell you estimates are lies? JOËL: Yes, a lot. It's maybe cynical, but there are a lot of cynics in our industry. STEPHANIE: That's true. Part of this story is me giving an estimate that was a lie. So, in some ways, there is a grain of truth to it [laughs]. But I wanted to share with you this experience I had a few weeks ago where I was in kind of a like, project status update meeting. And I was coming to this meeting for the first time actually. And so, it was with a group of people who I hadn't really met before. It was kind of a large meeting. So, there were a handful of people that I wasn't super familiar with. And I was coming in to share with this bigger group, like, how the work I had been doing was going. And during that time, we had gotten some new information that was kind of making us reassess a few things about the work, trying to figure out, like, where to go next and how to meet our ultimate goal for delivering this feature. With that new information in mind, one of the project managers was asking me how long I thought it might take. And I did not have enough information to feel particularly confident about an answer, you know, I just didn't know. And I mentioned that this was kind of my first time in this meeting. There were a lot of people I didn't know, including the person who was asking the question. And they were saying, "Oh, well, you can just guess or, like, you know, it doesn't have to be perfect. But could you give us a date?" And I felt really hard-pressed to give them an answer in that moment because, you know, I kind of was stalling a little bit. And there was still this, like, air of expectancy. I eventually, I have to say, I made something up [laughs]. I was like, "Well, I don't know, like, three weeks," you know, just really pulling it out of thin air. And, you know, that's what they put down on the spreadsheet, and then they moved on [laughs] to the next item. And then, I sat there in the rest of the meeting. And afterwards, I felt really bad. I, like, really regretted it, I think, because I knew that the answer I gave was mostly BS, right? Like, I can't even say how I came up with that. Just that I, like, wanted to maybe give us some extra time, in case the task ends up being complicated, or, you know, there are all these unknowns. But yeah, it really didn't feel good. JOËL: I'm curious why that felt bad. Was it the uncertainty around that number or the fact that the number maybe you felt like you'd given, like, a ridiculously large number? Typically, I feel like when estimates are for a story, it's, like, in the order of a few days, not a few weeks. Or is it something else, the fact that you felt like you made it up? STEPHANIE: I think both, where it was such a big task. The larger and higher level the task is, the harder it is to come up with an answer, let alone an accurate one. But it was knowing that, like, I didn't have the information. And even though I was doing as they asked of me [chuckles], it was almost like I lost a little bit of my own integrity, right? In terms of kind of based on my experience doing software development, like, I know when I don't know, and I wasn't able to say it. At least in that moment, didn't feel comfortable saying it. JOËL: Because they're not taking no for an answer. STEPHANIE: Yeah, yeah, or at least that was my interpretation of the conversation. But the insight or the learning that I took away from it was that I actually don't want to feel that way again [laughs], that I don't want to give a lie as an estimate because it didn't feel good for me. And the experience that I have knowing that I don't have an answer now, but there are, like, ways to get the answer, right? What I wish I had said in that meeting was that I didn't know, but I could find out, or, like, I would let them know as soon as I did have more information. Or, like, here is the information that I do need to come up with something that is more useful to them, honestly, and could make it, like, a win for all of us. But yeah, I've been reflecting on [chuckles] that a lot. Because, in a sense, like, I really needed to trust myself and, like, trust my gut to have been able to do my best work. JOËL: I wonder if there's maybe also a sense in which, you know, generally, you're a very kind of earnest person. And maybe by giving a ridiculous number there just to, like, check a box, maybe felt like you gave way to a certain level of cynicism that wasn't, like, true to who you are as a person. STEPHANIE: Yeah, yeah, that feels real [laughs]. JOËL: Have you ever done estimation sessions where you put error bars on your number? So, you say, hey, this is my estimate, but plus or minus. And, like, the more uncertainty there is around a number, the larger those plus or minus values are to the point where I could imagine something as ridiculous as like, oh, this is going to take three weeks, plus or minus three weeks. STEPHANIE: I like that. That's funny. No, I have not ever done that before or even heard of that. That is a really interesting technique because that seems just more real to me, where, again, people have different opinions about estimation and how effective or useful it is. But for organizations where, like, it is somewhat valuable, or it is just part of the process, I like the idea of at least acknowledging the uncertainty or the ambiguity or, like, the level of confidence, right? That seems like an important piece of context to that information. JOËL: And that can probably lead to some really interesting conversations as well because just getting a big number by itself, you might have a pretty high certainty. I mean, three weeks is big enough that you might say, okay, there's definitely going to be some fuzziness around that. But getting a sense of the certainty can, in certain contexts, I find, drive really interesting conversations about why things are uncertain. And then, that can lead to some really good conversations around scoping about, okay, so we have this larger story. What are the elements of it that are uncertain that you might even talk in terms of risk? What are the risky elements of this story or maybe even a project? And how do we de-risk those? Is there a way that we could remove maybe a small part of the story and then, all of a sudden, those error bars of plus or minus three weeks drop down to plus or minus three days? Because that might be possible by having that conversation. STEPHANIE: Yeah, I like what you said about scope because the way that it was presented as this really big chunk of work that was very critical to this deadline, there was no room to do scope, right? Because we weren't even talking about what makes up this feature task. We hadn't really broken it down. In some ways, I think it was very, like, wishful, right? To be like, oh yeah, we want this feature. We're not going to talk too much about, like, the specific details [laughs], as opposed to the idea of it, right? And that, I think, is, you know, was part of what led to that ambiguity of, like, I can't even begin to estimate this because, like, it could mean so many different things. JOËL: Right. And software problems, often, a slight change in the scope can make a massive change in complexity. I always think of a classic xkcd comic where two people are talking about a task, and somebody starts by describing something that kind of sounds complex. But the person implementing it is like, "Oh yeah, no, that's, you know, it's super easy. I can do that in half a day." And then, like, the person making the ask is like, "Oh, and, by the way, one small detail," and they add, like, one small thing that seems inconsequential, and the person is just like, "Okay, sorry, I'm going to need a research team and a couple of PhDs. And it's going to take us five years." STEPHANIE: That's really funny. I haven't seen this comic before, but I need to [laughs] because I feel that so much where it's like, you just have different expectations about how long things will take. And I think maybe that is where, like, I felt really disappointed afterwards. Because in my inability to, like, just really speak up and say, like, "In my experience, like, this is kind of what happens when we don't have this information or when we aren't sure," yeah, I just wasn't able to bring that to the table in that, you know, meeting. And I really am glad we're having this conversation now because I've been thinking about, like, okay, when I find myself in this position again, how would I like to respond differently? And even just that comic feels really validating [laughs] in terms of like, oh yeah, like, other people have experienced this before, where when we don't have that shared understanding or, like, if we're not being super transparent about how long does a thing really take, and why does it make it complex, or, like, what is challenging about it, it can be, like, speaking in [chuckles] two different languages sometimes. JOËL: I think what I'm hearing almost is that in a situation like what you found yourself in, you're almost sort of wishing that you'd picked one extreme or the other, either sort of, like, standing up to—I assume this is a project manager or someone...to say, "Look, there's no number I can give you that's going to make sense. I'm not going to play this game. I have no number I can give you," and kind of ending it there. Or, on the other hand, leaning into, say, "Okay, let's have a nuanced conversation, and we'll try to understand this. And we'll try to maybe scope it and maybe put some error bars on this or something and try to come up with a number that's a little bit more realistic." But by kind of, like, trying to maybe do a middle path where you just kind of give a ridiculously large number that's meaningless, maybe everybody feels unfulfilled, and that feels, like, maybe the worst of the paths you could have taken. STEPHANIE: Yeah, I agree. I like that everyone [laughs] feels slightly unfulfilled point. Because, you know, my estimate is likely wrong. And, like, what impact will that have on other folks and, you know, their work? While you were saying, like, oh yeah, here were the kind of two different options I could have chosen, I was thinking about the idea of, like, yeah, like, there are different strategies depending on the audience and depending who you're working with. And that is something I want to keep in mind, too, of, like, is this the right group to even have the, like, okay, let's figure this out conversation? Because it's not always the case, right? And sometimes you do need to just really stand firm and say, like, "I can't give you an answer. And I will go and find the people [laughs] who I can work this out with so that I can come back with what you need." JOËL: And sometimes there may be a place for some sort of, like, placeholder data that is obviously wrong, but you need to put a value there, as long as everybody's clear on that's more or less what's happening. I had to do something kind of like that today. I'm connecting with a third-party SAML for authentication using the service Auth0. And this third party I'm talking to...so there's data that they need from me, and there's data that I need from them. They're not going to give me data until I give them our data first, so this is, like, you know, callback URLs, and entity IDs, and things like that you need to pass. In order to have those, I need to stand up a SAML connection on the Auth0 side of things. In order to create that, Auth0 has a bunch of required fields, including some of the data that the third party would have given me. So, we've got a weird thing where, like, I need to give them data so they can stand up their end. But I can't really stand up my end until they give me some data. STEPHANIE: Sounds like a circular dependency, if I've ever heard one [laughs]. JOËL: It kind of is, right? And so, I wanted to get this rolling. I put in a bunch of fake values for these callback URLs and things like that in the places where it would not affect the data that I'm giving to the third party. And so, it will generate as a metadata file that gets generated and stuff like that. And so, I was able to get that data and send it over. But I did have to put a callback URL whose domain may or may not be example.com. STEPHANIE: [laughs] Right. JOËL: So, it is a placeholder. I have to remember to go and change it later on. But that was a situation where I felt better about doing that than about asking the third party, "Hey, can I get your information first?" STEPHANIE: Yeah, I like that as sometimes, like, you recognize that in order to move forward, you need to put something or fill in that gap. And I think that, you know, there was always an opportunity afterwards to fix it or, like, to reassess and revisit it. JOËL: With the caveat that, in software, there's nothing quite so permanent as a temporary fix. STEPHANIE: Oof, yeah [laughs]. That's real. JOËL: So, you know, caution advised, but yes. Don't always feel bad about placeholders if it allows you to unblock yourself. STEPHANIE: So, I'm really glad I got to bring up this topic and tell you this story because it really got me thinking about what estimates mean to me. I'm curious if any of our listeners if you all have any input. Do you love estimates? Do you hate them? Did our conversation make you think about them differently? Feel free to write to us at hosts@bikeshed.fm. JOËL: On that note, shall we wrap up? STEPHANIE: Let's wrap up. Show notes for this episode can be found at bikeshed.fm. JOËL: This show has been produced and edited by Mandy Moore. STEPHANIE: If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter. STEPHANIE: Or reach both of us at hosts@bikeshed.fm via email. JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week. ALL: Byeeeeeeeeeeeee!!!!! AD: Did you know thoughtbot has a referral program? If you introduce us to someone looking for a design or development partner, we will compensate you if they decide to work with us. More info on our website at tbot.io/referral. Or you can email us at referrals@thoughtbot.com with any questions.

Stephanie is engrossed in Kent Beck's Substack newsletter, which she appreciates for its "working thoughts" format. Unlike traditional media that undergo rigorous editing, Kent's content is more of a work-in-progress, focusing on thought processes and evolving ideas. Joël has been putting a lot of thought into various tools and techniques and realized that they all fall under one umbrella term: analysis. From there, Stephanie and Joël discuss all the productivity tricks they like to use in their daily workflows. Do you have some keyboard shortcuts you like? Are you an Alfred wizard? What are some tools or mindsets around productivity that make YOUR life better? Kent Beck’s Substack Tidy First? (https://tidyfirst.substack.com/) Debugging: Listing Your Assumptions (https://thoughtbot.com/blog/debugging-listing-your-assumptions) Dash (https://kapeli.com/dash) Alfred (https://www.alfredapp.com/) Rectangle (https://rectangleapp.com/) Meeter (https://apps.apple.com/us/app/meeter-for-zoom-teams-co/id1510445899) Vim plugins (https://github.com/thoughtbot/dotfiles/blob/main/vimrc.bundles#L32-L50) from thoughtbot’s dotfiles, including vim-projectionist () for alternate files Go To Spec VS Code plugin (https://marketplace.visualstudio.com/items?itemName=Lourenci.go-to-spec) Feedbin (https://feedbin.com/) Energy Makes Time by Mandy Brown (https://everythingchanges.us/blog/energy-makes-time/) Transcript: AD: Ruby developers, The Rocky Mountain Ruby Conference returns to Boulder, Colorado, on October 5th and 6th. Join us for two days of insightful talks from experienced Ruby developers and plenty of opportunities to connect with your Ruby community. But that's not all. Nestled on the edge of the breathtaking Rocky Mountains, Boulder is a haven for outdoor lovers of all stripes. Take a break from coding. Come learn and enjoy at the conference and explore the charm of Downtown Boulder: eclectic shops, first-class restaurants and bars, and incredible street art everywhere. Immerse yourself in the vibrant culture and the many microbrew pubs that Boulder has to offer. Grab your tickets now at rockymtnruby.dev and be a part of the 2023 Rocky Mountain Ruby Conference. That's rockymtnruby.dev, October 5th and 6th in Boulder. See you there. JOËL: Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Joël Quenneville. STEPHANIE: And I'm Stephanie Minn. And together, we're here to share a bit of what we've learned along the way. JOËL: So, Stephanie, what's new in your world? STEPHANIE: So, I have a new piece of content that I'm consuming lately. That is Kent Beck's Substack [chuckles], Kent Beck of Agile Manifesto and Extreme Programming notoriety. I have been really enjoying this trend of independent content creation in the newsletter format lately, and I subscribe to a lot of newsletters for things outside of work as well. I've been using an RSS feed to like, keep track of all of the dispatches I'm following in that way so that it also kind of keeps out of my inbox. And it's purely just for when I'm in an internet-reading kind of mood. But I subscribed to Kent's Substack. Most of his content is behind a subscription. And I've been really enjoying it because he treats it as a place for a lot of his working thoughts, kind of a space that he uses to explore topics that could be whole books. But he is still in the phase of kind of, like, thinking them through and, like, integrating, you know, different things he's learning, and acknowledging that, like, yeah, like, not all of these ideas are fully fleshed, but they are still worth publishing for people who might be interested in kind of his thought process or where his head is at. And I think that is really cool and very different from just, like, other types of content I consume, where there has been, like, a lot of, especially more traditional media, where there has been, like, more editing involved and a lot of time and effort to reach a final product. And I'm curious about this, like I mentioned, trend towards a little less polished and people just publishing things as they're working through them and acknowledging that the way they're thinking about things can change over time. JOËL: It sounds like this is kind of halfway between a book which has gone through a lot of editing and, you know, a tweet thread, which is pure stream of consciousness. STEPHANIE: Yeah, that's a really great insight, actually. And I think that might be my sweet spot in terms of things I enjoy consuming or reading because I like that room for change and that there is a bit of a, you know, community aspect to Substack where you can comment on posts. But, at least in my experience, has seemed, like, relatively healthy because it is, you know, you're kind of with a community of people who are at least invested or willing to pay [chuckles] for the content. So, there is some amount of good faith involved. His newsletter title itself it's called "Tidy First?" And so, that almost implies that it's, like, something he's still exploring or experimenting with, which I think is really cool. It's not like a I have discovered, like, the perfect way to do things, and, you know, you must always tidy first before you do your software development. He's kind of in the position of, this is what I think works, and this is my space for continuing to refine this idea. JOËL: I'm curious: are there any sort of articles that you've read or just thoughts in general that you've seen from Kent that are particularly impactful or memorable to you? STEPHANIE: Yeah. One I read today during my investment time is called Accountability in Software Development. And it was a very interesting take on the idea of accountability, not necessarily, like, when it's forced by others or external forces like a manager or, you know, your organization, but when it comes from yourself. And he describes it as a way to feel comfortable and confident in the work that he's doing and also building trust in himself and in his work but also in his teams. By being transparent and literally accounting for the things that he's doing and sharing them, communicating them publicly, that almost ends up diminishing any kind of, like, distrust, or shame, or any of those weird kind of squishy things that can happen when you hide those things or, like, hide what you're doing. It becomes a way to foster the good parts of working with other people but not in a necessarily like, resentful way or in a hierarchical way. I was really interested in the idea of accountability, ultimately, like, for yourself, and then that ends up just propagating to the team. JOËL: That's a really interesting topic because I think it sort of sits at the intersection of the personal and the technical. STEPHANIE: Yeah, absolutely. He mentions more technical strategies or tasks that kind of do the same thing. You know, he mentions test-driven development, as well as, like, a way of holding yourself accountable to writing software that, you know, doesn't have bugs in it. So, I think that it can be applied to, you know, exactly both of those, like, interpersonal stuff and also technical aspects too, anyway, that's what's new in my world. Joël, what about you? JOËL: So, this year, I've been putting a lot of thought into a variety of tools and processes. And I think I've come to the realization that they all really fall under one kind of umbrella term, and that would be analysis. It's a common step in some definitions of the traditional software development lifecycle. And it's where you try to after you've kind of gathered the requirements, try to break them down and understand what exactly that means from a technical perspective, what needs to happen. And so, a lot of the things that have been really fascinating to me this year have been different techniques that I can use to become better at that sort of phase. STEPHANIE: Wow. That's very powerful, I think. And honestly, the first thing that comes to mind is, how do you make time for it? JOËL: I think we all do it to a certain extent. You know, you pick up a ticket, and there is a prose description of some work to be done, hopefully not telling you directly, like, just go make a change to this class, but here's a business problem to be solved. And then you have to sort of figure out how to break it down. So, this can be as simple as, oh, what objects, what classes do I need to introduce for this change? But it might be more subtle in terms of thinking, okay, well, what are the edge cases I need to think about? Where are things that could fail, and how am I going to handle failure? So, there's a variety of techniques that you can use to get better at all of these. You can use them kind of at the micro level when thinking about just a ticket. You can use them when working on a larger epic, a larger initiative, a whole project because I think analysis fits into kind of all of these levels. And so, I think those are the techniques that have been most exciting to me this year and that have really connected. STEPHANIE: That is very exciting. It's triggering a lot of thoughts for me about how I incorporate analysis into my work and how that has actually evolved; where I think before, earlier in my career, I assumed that the analysis had been done by someone else who knew better than me or who knew more than me. And that by the time that you know, a piece of work kind of landed in my lap, I was like, okay, well, I just want to know what to do, right? Like, I want someone else to tell me what to do [laughs]. But now I think I have taken it upon myself to do more of that and, like, have realized that it's part of my role. And sometimes it will now be kind of a flag or, like, a signal to me when that hasn't been done. And I can tell when I receive a ticket, and it's, like, maybe missing the business problem or doesn't have enough information. And determining whether that is information that I need to go and find out, or if there's someone else who I can work together with to do that analysis with, or having a better understanding of, like, what is within my realm of analysis to do, and what I need to encourage other people to do analysis for before the work is ready for me. JOËL: I think there is an interesting distinction between more traditional requirements gathering and analysis, where traditional requirements gathering is getting all that business problem information from product people, from customers, things like that. The analysis step is often a little bit more about breaking down a business problem into, like, what are the technical ramifications of that? But there can be a little of a synergy there where sometimes, once you start exploring the technical side of it, it might bring up a lot of edge cases that have impacts on the product side, on the business side. And then you have to go back to the businesspeople and say, "Hey, we only talked about sort of the happy path. What happens if payment is declined? What do we want to do there?" And now we're back in sort of that requirements gathering phase a little bit more rather than purely analysis. But it can come out of an analysis phase where you've done maybe some state machine diagramming to try to better understand how things flow from one phase to another. Or maybe you were building out a truth table for some complex logic and realized, wait a minute, there's an edge case I didn't handle. It's not a strictly linear process. The two kind of feed into each other and, honestly, into the implementation side as well. STEPHANIE: Yeah, I'm with you there. I'm thinking about a piece of work that I've been working on, where we were thinking of doing a database migration and adding some new columns to a table. But the more I dug into it, the more I realized that that was the first idea or the immediate idea that came from a need that I had limited information about. And what was nice was I was able to sit on it for a little bit, get some input from others. And I realized that there were all of these things that I couldn't answer yet. And someone, I think literally asked in a code review if you've already done this analysis, between knowing that these columns will be the kind of extent of what you need versus, you know, will the data end up needing more columns? And should the data model be a little more flexible to that potential change? And they said, "If you had already done this analysis, then, like, otherwise, it looks good to me." And I was like, "Oh, I didn't." [laughs] And that encouraged me to go back to some cross-functional members of the team and ask more questions. And that has taken more time. That was another challenge that I had to encounter was saying like, "Yeah, we started this, and we made some progress. But actually, we need to revisit a few things, like a few parts of the premise, before continuing on." JOËL: Are there any techniques or approaches that you particularly enjoy when it comes to doing an analysis or that maybe are go-to's for you? STEPHANIE: Reminding myself to revisit my assumptions [laughs], or at least even starting by being really clear about what I'm assuming, right? Because I think that has to happen first before you can even revisit them is having an awareness of what assumptions you're making. And I actually think this is where collaboration has been really helpful, where I've been working on this task with another developer on my team. And when we've been talking about it, I found myself saying, "Oh, I'm assuming this," right? Or, like, I'm assuming that the stakeholder knows what they need [laughs]. And that's why we're going to do it this way, where we were kind of given the pieces of data that we should be persisting. And the more that we had that conversation, the more I realized, like, actually, like, I'm not convinced that they have that full picture of, like, what they need in the future. And because we're making this decision now, like, we are turning, you know, literally from, like, the abstract into, like, a concrete change [chuckles] in the database, now seems like...now that we're faced with that decision, it seems like a good time to revisit the assumption that I was making. And that has proved helpful in making ultimately, like, a more informed decision about, like, which way to go technically. But I personally have found a lot of value in verbally processing it with someone else. It's a lot harder for me to identify them, I think, when I'm in my own head. JOËL: That's really interesting that you keyed in on the idea of assumptions. I typically think of assumptions being, like, so important mostly in debugging rather than analysis. In fact, I wrote a whole blog post about why listing your assumptions is so important as part of your debugging process. Now, like, my mind is spinning a little bit. I'm like, oh, I wonder if I could use some of those, like, debugging techniques as part of more of my analysis step. And could that make me better? So, I think you've put me on a whole, like, thought track of, like, oh, how many of these debugging techniques can I use to make my analysis better? So, that's really cool. STEPHANIE: Yeah, and vice versa. So, a few minutes ago, I'd asked you how you make time for that analysis. Because I was thinking that, you know, in my day-to-day work, I'm juggling so many things. I often find myself running out of time and not able to do all of it. And that, I think, leads us really well into our topic for this episode, which is productivity tricks and ways that we make the most use out of our limited time. JOËL: I think I may have a maybe a bit of a controversial opinion on productivity tricks. I feel like a lot of productivity tricks don't actually make me that much faster. Like, maybe I save a couple of minutes a day, maybe 5 or 10 a day with productivity tricks. And, sure, that adds up over the course of a year. But there are other things I could do in terms of, like, maybe better habits, better managing of my schedule that probably have a much more significant impact. Where I think they are incredibly valuable, though, is not directly making me better with my time management but managing my focus, allowing me to kind of keep in the flow and get things done without getting sidetracked. Or just kind of giving me the things that I need in the moment that I need them so that I'm not getting on to a subtask that I don't really need to be doing. STEPHANIE: Yeah. I really like that reframing of what helps you focus because as I was brainstorming ways that I stay on track for my work, I think I ended up discovering a similar theme where it wasn't so much, like, little snippets and tools for me, as opposed to how I structure all of the noise, I guess, in my day-to-day work and being able to see what it is that I need to care about the most right now. JOËL: I think one of the things that I've tried to do for myself is to make it easy to have access to the information and the tools that I need. Probably one of the most useful bits of that is a combination of the documentation viewer Dash and the...I'm not sure what it would be called– launcher, productivity manager tool for Mac. Alfred, with a CMD + Space, it brings up this bar I can type into. And then you can trigger all sorts of things from there. And so I can type the name of a language or some kind of keyword that I have set up and the name of a method. And then, all of a sudden, it'll show me everything like, you know, top five results. And I can hit Enter, and it will bring up the documentation for that. So, if I want to say, oh yeah, what is the order of the arguments for Enumerable's inject method (which I constantly forget)? You know, it's a few keyboard shortcuts, you know, CMD + Space Ruby Enumerable inject. It's fuzzy finding, so I probably don't even need to type all of that. Hit Enter, and I have the documentation right in front of me. So, that makes it so that I can get access to that with very little amount of context shifting. STEPHANIE: Yeah. I like what you said about how the tools are really helping you, like, narrow down, like, the views of, like, what is most important for you in that moment, and it's doing a little bit of that work for you. I think the couple of tools and apps that I actually did want to share are kind of similar. One MacOS app I really like is called Rectangle for windows management, which is really crucial for me because I don't enjoy like, swiping and tabbing between applications. I would much prefer just seeing, usually, just two things. I try to keep my screen limited to two different windows at once because once it gets more than that, I'm already just, like, overwhelmed [laughs]. And as I'm trying to focus a little bit more on just having, like, one thing be the focus of my attention at a time, Rectangle has been really nice in just really quickly being able to do my windows resizing. So, I usually have, like, either things split between my screen half and half. Like, right now, I have your face on my screen as we record this podcast, and then my notes editing software for taking notes about what we talk about. During my development workflow, it's usually, you know, just my editor, my terminal, and then maybe my browser ends up being, like, the thing that I tab into. But I'm able to just, like, set that all up, and as I need those windows to change depending on what my focus has been shifted to, to kind of make more space for whatever I'm reading, or looking at, or processing visually. The keyboard shortcuts that Rectangle...that I have now, you know, ingrained into my fingers [laughs] has been really helpful. It's like, I'm not fussing with just, like, too many things open. JOËL: I have yet to, like, dive into a window manager. I'm still in the clunky world of CMD tabbing. But maybe I should give that a try. STEPHANIE: For me, it has helped even just, like, identify the things that I need to give more space to on my screen and aggressively, like, cut everything else [laughs]. So, that's a really great MacOS app. And then, the other one is actually kind of a similar vein. It's called Meeter, M-E-E-T-E-R. And it has been really helpful for managing my meetings, especially my video call meetings where the video call software that's being used for the meeting may be variable. And also, when I have multiple email addresses that meetings are being sent to, you're able to sign into all of your calendar accounts. And it provides a really nice view of all of your meetings. It has a really, like, minimal, I guess, design in your toolbar, where it shows you how many minutes until your next meeting. And from that toolbar button, you can click to go to the video conferencing software directly for whatever meeting is up next. And you don't have to, you know, scramble to open Google Meet, or Zoom, or Webex, or whatever it is. And that's [chuckles] been nice, again, just kind of, like, cutting down on the amount of stuff that I need to remember and shift through to get to my destination. JOËL: I think I'm hearing kind of two themes emerge out of some of the things that we've shared. And I'd like to maybe explore them a little bit; one is the power of keyboard shortcuts. And I think that's maybe what a lot of us think of when we think of productivity apps, at least developers, right? We love keyboard shortcuts. And then, secondly, I think I'm hearing automation, right? So, you don't have to go through and, like, find that email or calendar link to find the Zoom link or whatever. It shows up in your toolbar. So, maybe we can dig into a little bit of the idea of keyboard shortcuts. Are you a person who like customizes a lot of keyboard shortcuts? And is that a part of your kind of productivity setup? STEPHANIE: Well, a while ago, we had talked about not keyboard shortcuts in the context of productivity, but I think I had mentioned that I was trying to use my mouse less [chuckles] because I was getting a little bit of wrist pain. And I think that actually has rolled into a little bit of, you know, just, like, more efficient navigation on my computer. I think my keyboard shortcut usage is mostly around window management, like I mentioned. I do feel like I have, like, a medium amount of efficiency in my editor. Sometimes, when I'm pairing with other people who use Vim, I'm, like, shook by how fast they're moving. And I have figured out what works for me in VS Code, and I don't think I need to get any faster. You know, I've just accepted that [laughs]. In fact, it's almost, like, the amount of speed and friction that I have, in my experience, is actually a little more beneficial for the speed that my mind works [laughs]. It kind of helps me slow down when I need to think about what I'm doing as opposed to just, like, being able to, like, do anything at my fingertips, and kind of my brain is just not able to think that fast. And then navigating Slack, which is where I also spend a lot of my time on my computer. Now, using Slack with my keyboard shortcuts has been really helpful because, again, I'm not, like, mindlessly browsing or clicking around. I'm just looking at my unread messages. One non-keyboard shortcut I really like with Slack is Command + K, which is the jump-to feature. And so, I'm using that to go to a specific channel that I know I'm looking for or my own personal DMs, where I keep a lot of notes as well. And, honestly, I think that's, like, the extent of my keyboard shortcut usage. I'm curious what your setup is in regards to that, though. JOËL: I think I'm similar to you in that I have not kind of maxed out the productivity around keyboard shortcuts. You'd mentioned the jump to in Slack. Several pieces of software have something kind of like that. It might be some sort of omnibar, or a command palette, or something like that, where you really just need to know...CMD + K, or CMD + P, CTRL + P are common ones. Then you can sort of, like, type a few characters to just describe the thing you want to do, or a search you want to make, or something like that. Just knowing that one keyboard shortcut for your one piece of software gets you, I don't know, 80% of the productivity that you want. It's kind of amazing. I love the idea of an omnibar. STEPHANIE: Yeah, I hadn't heard of omnibar as a phrase before, but that feels very accurate. I like that a lot, too, where it's, like, oftentimes, I don't do whatever particular thing enough necessarily for it to justify a keyboard shortcut, for me at least. I'm still able to be fast enough to get to, like I said, that final destination or the action that I want to take with a more universal shortcut like that. JOËL: In my editor...so I use Vim, and I got used to Vim's keyboard-based navigation. And that is something that I deeply appreciate, maybe not so much for speed but being able to almost kind of feel one with the machine. And the cursor moves around, and I don't have to, like, think about moving it. It's really a magical sort of feeling. And it's become so much muscle memory now that I can just sort of...the cursor jumps around, things change out. And I'm not, like, constantly thinking about it to the point where now, if I'm in any other editor, I really want to get those shortcuts or, I guess, maybe not shortcuts but a Vim-style navigation, keyboard-based navigation. STEPHANIE: Yeah, it sounds like it's not so much the time savings but the power that you have or the control that you have over your tools. JOËL: Yes. And I think, again, the idea of focus. Navigation has stopped becoming a thing where I have to actively think about it. And I feel like I really do just sort of think my fingers are on the keyboard. I'm not having to, like, do a physical motion where I switch my hands. Like, I'm typing, and I'm writing code, then I have to switch my hand away to a mouse to shift around or, like, move my hand off the home row to, like, find the arrow keys and, like, move around. I just kind of think, and the cursor jumps up. It's great. Maybe I'd be the same if I'd put a lot of time into getting really good at, you know, maybe arrow-based navigation. I still think the mouse you have to move your hand off. It breaks just in the tiniest little way the flow. So, for me, I really appreciate being fully keyboard-based when I'm writing code. STEPHANIE: Right. Being one with the keyboard. As you were talking about that, I very viscerally felt, you know, when you encounter a new piece of technology, and you're trying to navigate it for the first time, and you're like, wow, like, that takes so much mental overhead that it's, you know, just completely disruptive to the goal that you're trying to achieve with the software itself. JOËL: Yeah, it is a steep learning curve. So, we've talked about custom keyboard shortcuts in the editor. But it's common for people to augment their editor with plugins, maybe even some kind of, like, snippet manager to maybe expand snippets or to paste common pieces in. Is that something that you've done in your editor setup? I think you said you use VS Code as your sort of daily editor. STEPHANIE: Yeah, that's right. I actually think I almost forgot about some of my little bits of automation because they are just so spelled for me [laughs] that I don't have to think about them. But you prompting me just now reminded me that there are a few that I'd like to shut out. Snippets-wise, I mostly use them for when I'm writing tests and just having the it blocks or the context blocks expand out for me so I don't have to do any of that typing of the setup there. And since I do use a terminal outside of my editor...I know that some people really like kind of having that integrated and being able to run tests even faster without having to switch to a different application, but I like having them separate. There is a really great plugin called Go to Spec where you can be in any, you know, application code file, and it will pull up the spec file for you. I've been really enjoying that, and that is what helps my test writing be a little more automated, even though I'm having it in separate applications. JOËL: That is really useful. So, as a Vim user, I also have a plugin that does something similar, where I can switch to what's considered the alternate for a particular file, which is typically the spec, or if I'm in the spec, it'll switch to the source file that the spec is testing. STEPHANIE: And then, I do have one really silly one, which is that I got so sick and tired of not remembering how to, you know, type the symbols for string interpolation in Ruby that has also become a snippet where the hash key and the [inaudible 28:48] brackets can [laughs] populate it for me. JOËL: I love it. So, Stephanie, I'd like to go back to something you were talking about earlier in the show. When you were sharing about what was new in your world and, you mentioned that you subscribe to the Substack and that you subscribe to, actually, a lot of newsletters, and you said something that really caught my attention. You were saying that you don't want these all cluttering up your email inbox. And instead, you send all of these to an RSS reader application. What kind of application do you like to use? STEPHANIE: I use Feedbin for this. And I actually think that this was recommended by Chris Toomey back in the day on a previous Bike Shed episode before you and I hosted the show. But that has been really awesome. It has a just, like, randomly generated email address you can use when you sign up for newsletters. You use that instead. And I really like having that distinction because I honestly treat my email inbox as a bit of a to-do list, where I am archiving or deleting a lot of stuff. And then the things that remain in my inbox are things that I need to either respond to, or do, or get back to in some way. And then yeah, when I've completed it, then that's when I archive or delete. But now that we do have all this great content back in email form, I needed a separate space for that, where I similarly kind of treat it as, like, a to-read list. And yeah, like, I look at my unreads in the newsletter RSS reader that I'm using and go through that when I'm in a blog-reading kind of mood. JOËL: I really like that separation because I'm kind of like you. I treat my inbox as a to-do list. And it's hard to have newsletters come in and, like, I'm not ready to read them. But I don't want them in my to-do, or, like, they'll just kind of sit there and get mixed in and maybe, like, filtered down to the bottom. So, having that explicit separation to say, hey, here's the place I go to when I am in a reading mood, then I can read things. I think there's also I've sort of trained myself to only check my email during certain times. So, for example, I will not check my work email outside of working hours. But if I'm on the subway going somewhere and I've got some time where I could do some reading, it would probably be a good thing to be going through some kind of newsletter or something like that. So, I either have to remember to go back to it, or what I tend to do is just scroll Twitter and hope that someone has shared that link, and then I read it there, which is not a particularly effective way of doing things. So, I might try the RSS feed reader tool. What was it called? STEPHANIE: Feedbin. JOËL: Feedbin. All right, I might try to get into that. STEPHANIE: Yeah, I look forward to hearing if that ends up working for you because I agree, having the two separate spaces has been really helpful because I don't want to get distracted by my email/to-do list inbox if I'm just wanting to do a bit of reading, enjoy some content. So, one more theme around productivity that I don't think we've quite mentioned yet, but maybe we've talked a little bit around, is the idea that it's, at least for me, it's a product of time and energy. So, even if you have all the time in the world, you know, you can just stare into space or, like, stare at a line of code and not get [laughs] anything done. JOËL: I know the feeling. STEPHANIE: Right? I am kind of curious how or if you have any techniques for managing that aspect. When your focus is low like, how can you kind of get that back so that you can get back to doing your tasks or getting what you need to do done? JOËL: If I have the time, taking a break is a really powerful thing, particularly taking a break and doing something physical. So, if I can go outside and take a walk around the block, that's really helpful. And if I need a shorter thing that can be done in, like, five minutes or something, I have a pull-up bar set up in my place. So, I'll just go up and do a few sets there and get a little bit of the heart rate slightly up, do a little bit of blood pumping. And that sometimes can help reset a little bit. STEPHANIE: Nice. Yes, I'm all for doing something else [chuckles]. Even when you know that this is a priority or is kind of urgent or whatever, but you just can't get yourself to do it, I've found that asking myself the question, "What would make this task easier for me right now?" has been helpful during those moments. And, for me, that might be grabbing a friend, like, maybe I'm blocked because I'm really just unmotivated. But having someone along can kind of inject some of that energy for me. And then, there's a really great blog post by a woman named Mandy Brown. It's called Energy Makes Time. And she talks about how doing the things that fill our cup, actually, you know, even though it seems like how could we possibly have time to be creative, or, like you said, maybe do something physical, those seem, like, lower on the priority list. But when you kind of get to the point where you just feel so overwhelmed and can't do anything else, and you just go do those things that you know feel good for you, you kind of come back with a renewed perspective on your to-do list. And you can see, like, what things actually aren't that critical and can be taken off. Or you just find that you have the capacity or the energy to get the things that you are really dreading out of the way. So, that has been really helpful when I just am feeling blocked. Instead of, like, feeling bad about how unproductive [chuckles] I'm being, I take that as a sign of an opportunity to do something else that might set me up for success later. JOËL: Yeah. I think oftentimes, it's easy to think of productivity in terms of, like, how can I maybe eliminate some tasks that are not high value through clever automation, or keyboard shortcuts, or things like that? But oftentimes, it can be more about just sort of managing your focus, managing your energy. And by doing that, you might have a much higher impact on both how productive you feel—because that's an important thing as well, in terms of motivation—and, you know, how productive you actually are at getting things done. STEPHANIE: Right. At least for me, like, not all TDM is bad and needs to be automated away, but, like, my ability to, like, handle it in the moment. Whereas yeah, sometimes maybe I've just run the same few lines that should be just a script [chuckles], that should just be, you know, one command, enough times that I'm like, oh, like, I can't even do this anymore because of just, like, other things going on. But other times, like, it's really not a big deal for me to just, you know, run a few extra commands. And, like, that is perfectly fine. JOËL: I love writing a good Vim macro. Yeah. So, it's important to think beyond just the fun tools and the code that we can write. Kind of think a little bit more at that energy and that mental level. That said, there are a ton of great tools out there. We've named-dropped a bunch of them in this episode. For our listeners who are wondering or who weren't, like, necessarily taking notes, we've linked all of them in the show notes: bikeshed.fm. You can find them there. STEPHANIE: On that note, shall we wrap up? JOËL: Let's wrap up. STEPHANIE: Show notes for this episode can be found at bikeshed.fm. JOËL: This show has been produced and edited by Mandy Moore. STEPHANIE: If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter. STEPHANIE: Or reach both of us at hosts@bikeshed.fm via email. JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week. ALL: Byeeeeee!!!! ANNOUNCER: This podcast is brought to you by thoughtbot, your expert strategy, design, development, and product management partner. We bring digital products from idea to success and teach you how because we care. Learn more at thoughtbot.com.

Joël describes an old-school object orientation exercise that involves circling nouns in a business problem description. The purpose is determining which nouns could become entities or objects in a system. Stephanie shares she's working from the Hudson Valley in New York as a trial run for potentially relocating there. She enjoys the rail trails for biking and contrasts it with urban biking in Chicago. The conversation between Joël and Stephanie revolves around mentorship, both one-on-one and within a group setting. They introduce a new initiative at thoughbot where team members pair up with principal developers for weekly sessions, emphasizing sharing perspectives and experiences. Socratic method (https://tilt.colostate.edu/the-socratic-method/) Mentorship in 3 Acts by Adam Cuppy (https://www.youtube.com/watch?v=eDX5WH1uLz8) Exercism mentoring (https://exercism.org/mentoring) Transcript: STEPHANIE: Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Stephanie Minn. JOËL: And I'm Joël Quenneville. And together, we're here to share a bit of what we've learned along the way. STEPHANIE: So, Joël, what's new in your world? JOËL: I was recently having a conversation with a colleague about some old-school object orientation exercises that people used to do when trying to do more of the analysis phase of software, ones that I haven't seen come up a lot in the past; you know, 5, 10 years. The particular one that I'm thinking about is an exercise where you write out the sort of business problem, and then you go through and you circle all of the nouns in that paragraph. And then, from there, you have a conversation around which one of these are kind of the same thing and are just synonyms? Which ones might be slight variations on an idea? And which ones should become entities in your system? Because, likely, these things are then going to be objects in the system that you're creating. STEPHANIE: Wow, that sounds really cool. I'm surprised that it's considered old school or, I guess, I haven't heard of it before. So, it's not something in my toolbox these days. But I really like that idea. I guess, you know if you're doing it on pen and paper, it's obviously kind of timeless to me. JOËL: And you could easily do it, you know, in a Google Doc and underline, or highlight, or whatever you want to do. But it's not an exercise that I see people really doing even at the larger scale but even at, the smaller scale, where you have maybe a ticket in your ticketing system, and it has a paragraph there kind of describing what needs to be done. We tend to just kind of jump into, oh, we're going to build a story and do the work and maybe not always think about what are the entities that need to happen out of that. STEPHANIE: I think the other thing that I really like about this idea is the aligning on shared vocabulary. So, if you find yourself using different words for the same idea, is that an opportunity to pick the vocabulary that best represents what this means? Rather than a situation that I often find myself in, where we're all talking about the same things but using different words and sometimes causing a little bit more confusion than I think is necessary. JOËL: Definitely. It can also be a good opportunity to connect with the product or businesspeople around; hey, here are two words that sound like they're probably meaning the same thing. Is there a distinction in your business? And then, you realize, wait a minute, a shopping cart and an order actually do have some slight differences. And now you can go into those. And that probably sparks some really valuable learning about the problem that you're trying to solve that might not come up otherwise, or maybe that only comes up at code review time, or maybe even during the QA phase rather than during the analysis phase. STEPHANIE: Yeah. I think that's really important for us as developers because, as we know, naming is often the hardest part of writing code, right? And, you know, at that point, you are making that decision or that distinction between maybe a couple of different terms that you're using to describe an idea and putting that down then will continue on to be read. And just propagating that down the line of, is this name actually what we mean? Or maybe we are using words that, at this lower level, make more sense, but when interacting or communicating with business stakeholders or product folks, they are using a different term. And I really like the idea of that activity being a cross-functional one where you can kind of agree on how to move forward there. Because lately, I've been finding myself oftentimes using both words where the product folks are describing it this way, and then we've, on the engineering side, have decided that, okay, we're actually going to call our database table this other thing, and now having to type out both [chuckles] meanings each time because I know that my audience is in both camps. JOËL: Yeah. There's, I think, a lot of value in using the business terms where possible. If you don't use them, there has to be a good reason. There's a slight distinction for the technical term. We're using it to say, hey, it's different from the business idea in interesting ways that only matter to the dev team. STEPHANIE: Is there a name for this activity? JOËL: I don't know, just circling nouns or underlining nouns. STEPHANIE: Cool. Maybe we can come up with something. [laughs] Or someone else can tell us if they know what this kind of exercise is called. JOËL: Gotta name the naming activity. So, how about you, Stephanie, what's new in your world? STEPHANIE: So, I have a pretty exciting life development to share. I am currently working from a different location than my home in Chicago. I'm in the Hudson Valley in New York for the next month because my partner and I are considering moving out here. And we are just kind of looking for a different pace of life a little bit. And we are taking this month as a trial run to see if we want to, you know, be out here permanently. And I've been having a great time so far. One thing that I've really enjoyed is all of the rail trails out here. So, a lot of old railroad tracks have been repurposed for outdoor recreation, and they are great for biking, or running, or even just walking. And I've been able to hop on my bike, you know, and bike a few minutes, and then I'm on the trail and just kind of surrounded by trees and forests. And that's been really nice because I missed having access to nature kind of, like, right outside my door. JOËL: So, you used to do quite a bit of urban biking in Chicago. But it sounds like now you're getting a chance to do more kind of nature biking. STEPHANIE: Yeah, it's a big difference for me because urban biking was always pretty rough or a little scary just, you know, having to bike with traffic. And I got a lot better at it. But now I'm, you know, biking completely off the roads. And I don't have to worry too much about cars. And I can, you know, just enjoy the fresh air around me and just be a lot more relaxed, I think, than I was able to when I was commuting in the city. JOËL: So, here's the real question. At this new location that you're staying at, do you have a bike shed? STEPHANIE: Not yet. But we now could have a bike shed because there's a lot more space out here, too. So, I could theoretically have my bike shed in my nice, big yard right next to my garden. And these are all [laughs] the hopes and dreams I have for my future life. JOËL: Before you build the bike shed, you can have six months of discussion about what color you want to paint it. STEPHANIE: Yeah, that's why I have this podcast, actually. [laughter] So, look out for that in what's new in my world is considering paint colors for a theoretical future bike shed in a place where I yet don't live. JOËL: You're going to become an expert in the Pantone color palettes. STEPHANIE: I hope so. That would be a great addition to my title. So, another thing that's new in both of our shared worlds is a new initiative on Boost, the team we're on, that you have been involved in. It's pairing sessions with the principal developer. JOËL: Yes. So myself and, another principal developer at thoughtbot have been doing weekly pairing sessions, where we take Tuesday afternoons and pair with one of the other members of the team on their client project doing whatever. So, it's not, a, like, pull someone in when you need help or anything that's more kind of targeted in that way. It's more of a you sign up for this ahead of time. And you just know that on this week, you get someone to pair with you who can hopefully bring in a different perspective a lot of experience, and pair with you on your particular project. STEPHANIE: Yeah. I'm so excited about this initiative because I've not been staffed on a project with you before or the other principal developer who's involved. And I have really wanted to work with you all and be able to learn from you. And I think this is a really cool way to make that expertise more accessible if you just don't happen to be working on a project together. JOËL: Yeah. One of the challenges I think of the principal role is that we want it to be a role that has a high impact on the team as a whole. But also, we are people who can be staffed on pretty much any client project that gets thrown at us and can easily be staffed on projects that require solo work. Whereas there are some teammates who I think it's the developer position that we guarantee they're never staffed solo. And so, that can often mean that our principals get staffed on to the really technically challenging problems or the solo problems, but then there's maybe not as much room to have interactions with the rest of the team on a day-to-day basis. STEPHANIE: Yeah. I think the key word you said that had me nodding my head was impact. And I'm curious what your hopes are for this effort and what kind of impact you want to be having for our team. JOËL: I think it's impact on a few different levels, definitely some form of knowledge sharing. Myself and the other principal developer have decade plus experience each in the field, have deep knowledge in a lot of different things like test-driven development, object modeling, security, things like that that build on top of kind of more basic developer skills that we all have. And those are all, I think, great ways that we can support our team if there's any interest in those particular skills or if they come up on a particular project. And knowledge sharing works both ways, right? I think anytime you're pairing with someone else, there's an opportunity to learn on both sides. And so, I think a really important thing when you're pairing with someone, even if you're kind of maybe more explicitly the mentor figure, is to kind of keep that open mind and look for not only what can I give, how can I teach, but what can I learn from this other person? STEPHANIE: Yeah, absolutely. I guess I'm wondering...and I know this is a pretty new programming so far, but is there anything you've learned or anything that surprised you that you weren't expecting when you, you know, first conceived of the idea based on how it's been going? JOËL: Something that really surprised me, there's some feedback I got after one of the pairing sessions, where this colleague who we'd paired together...and I felt like I hadn't contributed a ton, like, this colleague just really had it and was just kind of going through and doing things. So, I was kind of, like, leaving that pairing session being like, oh, I don't know if I added a ton of value here. And then, this colleague reached out to me and said, "Oh, you know, I felt, like, this huge boost of confidence because we were pairing together, and you were just kind of nodding along and basically saying yes to all of my choices." And I hadn't really considered that that can be a really valuable aspect of this sort of pairing. Sometimes you know the right thing to do, like, you've got it. But it's really easy to second-guess yourself. And just having someone along to, you know, give you that thumbs of like, yeah, this is the thing to do, can give you that confidence boost and kind of keep you moving in a way that feels really positive. STEPHANIE: Wow. I love that. That's really powerful, and I get that. Because, you know, obviously, it's very valuable to have your colleagues help generate different ideas that you might not have considered. But that validation can be really useful. And, you know, that's just not something you get when with a rubber duck. [laughs] The rubber duck can't respond, and [laughs] nod along. So, I think that's really cool that you were able to provide some of that confidence. And, in fact, I think that is contributing to their growth, right? In terms of helping identify, you know, those aspects that they're already really strong at, as well as developing that relationship so they know you're available to them next time if they do need someone to either do that invalidating or validating of an idea. JOËL: Yeah, there's a lot of power, I think, in kind of calling out people's strength and providing validation in a way that can really help someone get to the next level in their career. And it feels like such a simple thing. But yeah, sometimes you can have the biggest impact not by kind of going in and helping but just kind of maybe, like, standing back a little bit and giving someone a thumbs up. So, definitely one of the biggest surprises or, I think, one of the biggest lessons learned for me in the past few weeks of doing this. STEPHANIE: That's very cool. JOËL: So, Stephanie, you've also been doing some pairing or some mentoring from what I hear. STEPHANIE: Yeah. So, on my current client work, I have been pairing with a new hire on my client team who recently graduated from college. And this is his first job in software development. And I have been thinking and learning a lot through this experience because one of my goals was to get better at coaching, specifically the idea of asking guiding questions to help someone, you know, arrive at their own solution instead of, you know, making the suggestions myself or kind of dictating where to go. And this has kind of been a progression for me of kind of starting from, well, you know, I have the way that I want to do it. And the person I'm working with who maybe has less experience, like, they might not know where to go. So, we're just going to go along with my idea. And then the next step was offering a few different ideas, like a menu of options and kind of having that discussion about which way to go. And now, I really wanting to practice letting someone else lead entirely and helping them start thinking about the right things but ultimately not giving them the answer. But hopefully, like, the questions I've been asking means that they are able to get to a well-informed answer where they've thought through some of the things that I would think about if I were in the position of making the decision or figuring out how to implement. JOËL: Is this mostly asking questions to get them to think about edge cases, or is this, like, a Socratic approach to teaching? STEPHANIE: Could you describe Socratic approach for me? JOËL: So, the Socratic approach is a teaching approach that is question-based, where you kind of help the student come to the conclusions themselves by answering questions rather than by telling them the answer. STEPHANIE: Oh, interesting. I think a little bit of both. Where it's true, I am able to see some edge cases that folks with less experience might not consider because they just haven't had to run into them before or fight the fires when [laughs] their code in production ends up being a big issue or causes a bug. But I think that's just part of the work where there is kind of, like, a default dynamic that might be fallen into when two people are working together, and their experience levels differ, where the person who has less experience is wanting to lean on the more senior person to tell them where to go, or to expect to be in that position of just learning from them and not necessarily doing as much of the active thinking. But I was really interested in flipping that and doing a bit of a role reversal because I think it can be really impactful and, you know, help folks earlier in their career, like, really level up even more quickly than just watching, but actually doing. And so, the questions I've been asking have been a lot more open-ended in terms of, like, asking, "What do you think about this code that we're looking at?" Or, like, "Where do you want to go next?" And based on, you know, their answers, digging in a little more, and, at the end, maybe, like, giving that validation that we were talking about earlier. I was like, "Great. Like, I think that's a great path forward," or, "I think that's a good idea to spend our time on right now." But the open-ended questions, I think, are also ones that I also would have liked when I was in that position of learning, where having someone trust that I could draw on my past experience but, like, also knowing that they were there to support and maybe orient me if I ended up straying too far off the path. JOËL: How have you navigated situations where maybe you're asking a question about "What do you want to do next?" and they pick something that maybe would work but is not your sort of preferred approach, or maybe something that seems like it would work well enough but, you know, there's maybe a better approach? How do you navigate that? Do you let them take their approach and maybe kind of let them run into some of the edge cases and problems and then say, "Hey, let me show you something new"? Do you probe a little bit earlier? Or do you say, "Hey, that's good, but why don't we try my way"? How do you navigate that kind of situation? STEPHANIE: That is so hard. It's really challenging. Because if you kind of know that there's maybe a more effective way, or a cleaner way, or whatever, and you're seeing your pair or your mentee kind of go down a different path, you know, it's so easy to just kind of jump in and be like, "Oh, actually, like, let me save you some time, and effort, and pain and just kind of tell you that there's something else we could try." But I think I've been trying to sit on my hands a little bit and let them go down that path or at least let them finish explaining kind of what their thought process is and giving them the opportunity to do that act of thinking to see it through without interrupting them because I think it's really important to, you know, just honor the process that they're going through. I will say, though, that I also try to keep an eye on the time. And I am also, like, holding in my head a bit of a higher level, like, the project status, any deadlines, what's on our plate for the sprint. And so, if I'm seeing that maybe the path they want to go down might end up taking a while or we don't quite have enough time for that, to then come back and revisit and adjust and reiterate on, like, their first solution. Then that is usually an opportunity where I might offer them another way or say, like, "Hey, like, this is what I'm thinking," because of those things I mentioned before with deadlines or something I'm considering. But I generally try not to impose any of that as, like, this is what we will do so much as saying, "This is what I think we should do." Because I really want to hone in on the idea that, like, everyone just has opinions [laughs] about how they want to do things. And I'm not claiming mine is the perfect way or even the best way, but just what I'm thinking in this moment. JOËL: Yeah, time permitting, I've really appreciated scenarios where you give people a chance to do the non-optimal solution and run into edge cases that kind of show why that solution is not optimal and then backtrack out of it and then go to the optimal path. I think that's a lesson that really sticks much longer. So, I've even done that in scenarios where I'm building some training material. And I'll kind of purposely have the group go down the sort of obvious path, but that turns out to be non-optimal. And then, you hit a wall where things don't work, and then you have to backtrack. And it's like, okay, so that's why we don't do it that way that may have seemed obvious. Because then everybody remembers as opposed to...I mean, you could just go down this other path, and somebody asks you a question, "Why don't we go down this thing?" And then, they just...maybe they have to remember it, or it becomes a thing where it's like, oh, but, like, we were told that's a bad way to do it. And now you have this sort of, like, weird, like, absolutism about, like, oh, but, you know, Joël said that was bad. So, we just got to remember that's the bad thing. And it's not about the morality of that choice that I think can come through when you're kind of declaring a path good and a path bad, but instead, having experienced, hey, we went down this path. There were some drawbacks to it, which is why we prefer this other path. And I think that tends to stick a lot more with students. STEPHANIE: Yeah. I really like what you said about not wanting to inject that, like, morality argument or even kind of deny them the opportunity to decide for themselves how they thought that path went or, like, how they thought the solution was. If you just tell them like, "No, don't go there," you're kind of closing the door on it. And, yeah, they might spend a lot of time afterwards thinking that, like, that will always be a bad option without really forming an opinion for themselves, which I think is really important. Because, you know, once you do get more experience, that is pretty much, like, the work [laughs] that we're doing all of the time. But another thing that I think is also such a skill is assessing your own work, like, after you go down the path or, like, once you have something working, being able to come back to it and look at it and be like, oh, like, can this be better, right? And I think that can only happen once you have something to look at, once you have, like, a first draft, if you will, or do the less optimal implementation or naive implementation. JOËL: So, when you're trying to prompt someone to kind of build that skill of self-review or self-reflection on some of the work that they've done, how do you as a pair or a mentor help stimulate that? STEPHANIE: Yeah. I think with early career folks, one thing that is an easy way to start the conversation is asking, "Are there any places that could be more readable?" Because that's, I think, an aspect that often gets forgotten because they're trying to hold so much in their heads that they are really just getting the code to work. And I think readability is something that we all kind of understand. It doesn't include any jargon about design patterns that they might not have learned yet. You know, even asking about extracting or refactoring might be not where they are at yet. And so, starting with readability, for example, often gets you some of those techniques that we've learned that have, you know, specialized vocabulary. But I have found that it helps meet them where they're at. And then, in time, when they do learn about those things, they can kind of apply what they've already been doing when kind of prompted with that question as, like, oh, it turns out that I was already kind of considering this in just a different form. JOËL: And I think one thing that you gain with experience is that you have kind of a live compiler or interpreter of the language in your head. And so, sometimes for more complex code, I, as an experienced developer, can look at it and immediately be like, oh yeah, here's some edge cases where this code isn't going to work that someone newer to the language would not have thought of. And so, sometimes the way I like to approach that is either ask about, "Oh, what happens in this scenario?" Or sometimes it's something along the lines of, "Hey, now that we've kind of done the main workflow, there's a couple of edge cases that I want to make sure also work. Let's write out a couple of test cases." So, I'll write a couple of unit tests for edge cases that I know will break the code. But even when we write the unit tests, my pair might assume that these tests will pass. And so, we'll write them; we'll run them and be like, "Oh no, look at that. They're red. I wonder why." And, you know, you don't want to do it in a patronizing way. But there's a way to do that that is, I think, really helpful. And then you can talk about, okay, well, why are these things failing? And what do we need to change about the code to make sure that we correctly handle those edge cases? STEPHANIE: Yeah, that's really great. And now, they also have learned a technique for figuring out how to move forward when they think there might be some edge cases. They're like, oh, I could write a test, and they end up [laughs] maybe learning how to do TDD along the way. But yeah, offering that strategy, I think, as a supplement to having supported them in their workflow, I think, is a really cool way to both help them learn a different strategy or tactic while also not asking them to, like, completely change the way that they do their development. JOËL: So, we've talked about ways that we can coach and mentor in a more of a one-on-one setting. But it can also happen in more of a group setting. And an initiative that I've been involved in recently is, once a quarter, the principals on thoughtbot's Boost team are running a training session on a topic that we choose. And we chose this month to make it really interactive. We created an exercise. We talked a little bit about it, had people break out into breakout rooms for a pretty short time—it was like 20 minutes—and come up with a solution. And then brought it back to the big group to talk through some of the solutions. All of that within 45 minutes, so it's a very kind of dense-packed thing. And I think it went really well. STEPHANIE: Yeah. So, hearing that makes me think that the group wasn't actually going to get to a solution in necessarily that short amount of time. But I'm wondering if that was maybe intentional. Like it was never really about coming to the optimal solution but just the act of thinking about it or practicing how you would do that problem-solving without as much of a focus on the outcome. JOËL: So, yes and no. I think, as you said, the discussion, the journey is more important than the outcome. But also, because we wanted people to have a realistic chance at coming up with some kind of solution, we specifically said, "We don't want code. Don't write a code solution to this." Instead, we suggested people come up with some kind of diagram. So, the problem was, we have some sort of business process where you start by...you have an endpoint that needs to receive some kind of shopping cart JSON and then goes through a few different steps. You have to validate it. You have to attempt to charge their card, and then eventually, it has to be sent off to a warehouse to be fulfilled. And so, we're asking them to diagram this while thinking a little bit about data modeling and a little bit about potential edge cases and errors. People came up with some really interesting diagrams for this because there's multiple different lenses from which you could approach that problem. STEPHANIE: That's cool. I really like that you left it up to the groups to figure out, you know, what kind of tools they wanted to use and the how. You mentioned different lenses. So, I'm taking it that you didn't necessarily share what the steps of starting to consider the data modeling would be. Did you prompt the group in any way? How did you set them up before they broke out? JOËL: So, we had a document that had a problem definition; part of this involved talking to a few external services, so things like attempting to charge their card. I think there was a user service they needed to do to pull some user information. And then, there's that fulfillment center that we submit to the warehouse with your completed order. And so, we had sample JSONs for all of these. Again, the goal is not for them to write any code that deals with it but more to think about: okay, we need information from this payload to plug into this one. And then, if they want to add any sort of intermediate steps, they can do that. And I think sort of two common lenses that you could look at this is from more of an action standpoint, so to say, okay, well, first, we receive this payload, and then we make a call to this endpoint, and we try to do a thing and then success or failure, and then kind of go down this path and success or failure, and kind of keep going down that path until you finally reach that fulfillment endpoint. So, it's almost like a control flow diagram. But you could also take more of a data-centered approach and talk about how the data evolves as it goes through this process. And so, you start with, like, a raw JSON payload. And maybe that gets parsed into a shopping cart object, which then gets turned into a temporary order, which then gets turned into a validated order, which then is combined with a credit card charge to create a fulfillment order, which can then be sent off to the warehouse. And that perspective will completely change the way you think about what the code actually needs to be when you create it. STEPHANIE: Got it. That's cool. So, I'm curious, you know, what went into figuring out what the prompt would look like? I guess, like, where did you start? Did you already know that there would be these two different ways of thinking about or lenses to data modeling that you're, like, oh, like, maybe these groups will go down this route? Or was it, I guess, a bit of a surprise that when you came together, you found out kind of the different approaches? JOËL: We already knew that there would be multiple approaches, and we chose not to specify which one to take. I think now this is getting into almost like curriculum design and more kind of the pedagogy side of things, which I'm, you know, excited and passionate about. I don't know, is that something that you've done at all for some of your projects or areas where you've been coaching people? STEPHANIE: It's not been. But I actually do think it's a bit of a goal of mine to lead a workshop at some point at a conference because I really like the hands-on stuff that I get to do day-to-day, you know, working one-on-one with people. And, you know, I also am on the conference circuit. [laughs] And I was thinking that maybe workshops could be a really cool way to bring together those two things of like, well, I am enjoying that experience of working one-on-one, but it is, oftentimes, you know, just on our regular day-to-day work. And so, I would be really curious about how to develop that kind of curriculum for teaching purposes. Do you find yourself starting with problems you see on client work and kind of stripping that down into something maybe a little more general, or do these problems kind of just come up spontaneously? [chuckles] JOËL: So, workshop design is, I think, its own really fascinating topic, and honestly, we could probably do a whole episode on it. But the short of it is I typically work backwards from an end goal. So, just like when I'm writing a blog post, I have one big thing I want people to learn from a workshop, and then everything works backwards from there. Anything that is part of the workshop has to be building towards that big goal, that one thing I want people to learn. Otherwise, I strip it out. So, it's an exercise in ruthlessly cutting to make sure that I'm not overwhelming people and, you know, that we can fit in the time that we have because there's always not enough time in a workshop. And people can very easily get sidetracked or overwhelmed. So, as much as possible, have everything focusing in towards one goal. Circling back to the mentoring side of things, I'm curious what you see is maybe some of the biggest challenges as a mentor or a coach. STEPHANIE: Well, I think, for me, it was, in some ways, like, seeing myself in that role as mentor. Like, oftentimes, that was decided for me by someone else as, like, "Oh, hey. We have a new hire, and, like, would you be their onboarding buddy?" Or, you know, a manager kind of identifying, like, oh, like, Stephanie has been in this role for, you know, a few years now. She's surely ready to mentor [laughs] new folks or people joining the team. And that was really hard for me because I was like, well, I still have so much to learn [laughs], you know, like, how could I possibly be in that position now? You know, I am still learning from all these other people who are mentors to me. So, one thing that took me a long time was learning that I did have things that I knew that other people didn't. And I started to think of it more as this, like, ring of overlapping circles where, you know, we all probably do share some common knowledge. But we all are also experts in different things, and everyone always has something to teach. Even if you're just, like, a few months or, like, a year ahead of someone else, that is actually a really powerful spot to cultivate peer mentorship, and where I think learning can really thrive. There's a really great talk about this by Adam Cuppy called Mentorship in Three Acts, where he talks about that peer mentorship, where someone just knows, like, a little more than someone else. That can be really powerful and can be a good entry point for people who are interested in getting into mentorship but are kind of worried that, like, oh, they are, you know, not a senior yet. You know, when you're at a similar experience level as who you're working with, there is a little bit less of what we were describing earlier of, like, that dynamic of knowing what to do but kind of wanting to hold back and let them discover for themselves. In that peer mentorship dynamic, you know, both people are, like, really deep in it, kind of trying things out, experimenting, learning, and that ends up being really fruitful time for both of them. JOËL: Based on your experience, would you say that maybe that's the best place to start for someone who's looking to get into mentorship, so kind of pursue more of a peer mentorship scenario? STEPHANIE: Yeah. I would definitely say that it has helped me a lot. I've had a lot of peer mentorship relationships in the past, where maybe there just wasn't someone on the team who could mentor me at the time. Or maybe I was wanting to collaborate a little bit more and feeling like I did have some ideas and opinions that I wanted to talk about, or share, or get some feedback on. Reaching across my level was really helpful in starting to create that space. Yeah, I was really surprised by all the things that I was learning and all the things that the other person was learning from me that I think was a good wealth of experience for me to then bring to the next step when I found myself kind of in that position of supporting others who were more junior. JOËL: I'd like to also shout out Exercism.io as a great place to get started with mentoring. For those who are not aware, Exercism is a platform where they have a bunch of exercises that you can go through to learn a language. And you can go through them on your own, but you can also go through them with a mentor. Somebody will basically give you a little mini code review on your exercise or maybe help you out if you're stuck. And this all happens asynchronously. And it's volunteer-run. So, they just have people from the community who volunteer to be mentors on there to help coach people through the exercises. We'll put a link in the show notes to the page they have, kind of explaining how the mentorship works and how to sign up. But I did that for a while. And it was a really rewarding experience for me. I thought that I'd be mostly helping and teaching, but honestly, I learned so much as part of the process. So, I would strongly recommend that to anybody who wants to maybe dip their toe a little bit in the mentoring coaching world but maybe feels like they're not quite ready for it. I think it's a great way to start. STEPHANIE: Ooh, that sounds really cool. Yeah, I know that, especially for folks who maybe are working a little bit more independently, or are a bit isolated, or don't have a lot of people on a team that they're able to access; that sounds like a really great solution for folks who are looking for that kind of support outside of their immediate circle. On that note, shall we wrap up? JOËL: Let's wrap up. STEPHANIE: Show notes for this episode can be found at bikeshed.fm. JOËL: This show has been produced and edited by Mandy Moore. STEPHANIE: If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter. STEPHANIE: Or reach both of us at hosts@bikeshed.fm via email. JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week. ALL: Byeeeeeee!!!!!!!! ANNOUNCER: This podcast is brought to you by thoughtbot, your expert strategy, design, development, and product management partner. We bring digital products from idea to success and teach you how because we care. Learn more at thoughtbot.com.

Stephanie has another debugging mystery to share. Earlier this year, Joël mentioned that he was experimenting with a bookmark manager to keep track of helpful and interesting articles. He's happy to report that it's working very well for him! Together, they discuss tactics to ensure the easiest route also upholds app health and aids fellow developers. They explore streamlining test fixes over mere re-runs and how to motivate desired actions across teams and individuals. Raindrop.io (https://raindrop.io/) Railway Oriented Programming (https://fsharpforfunandprofit.com/rop/) Transcript: JOËL: Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Joël Quenneville. STEPHANIE: And I'm Stephanie Minn. And together, we're here to share a bit of what we've learned along the way. JOËL: So, Stephanie, what's new in your world? STEPHANIE: So, I have another debugging mystery to share with the group. I was working on a bug fix and was trying to figure out what went wrong with some plain text that we're rendering from a controller with ERB. And I was looking at the ERB file, and I was like, great, like, I see the method in question that I need to go, you know, figure out why it's not returning what we think it's supposed to return. I went down to go check out that method. I read through it ran the tests. Things were looking all fine and dandy, but I did know that the bug was specific to a particular, I guess, type of the class that the method was being called on, where this type was configured via a column in the database. You know, if it was set to true or not, then that signaled that this was a special thing. You know, I made sure that the test case for that specific type of object was returning what we thought it was supposed to. But strangely, the output in the plain text was different from what our method was returning. And I was really confused for a while because I thought, surely, it must be the method that is the problem here [laughs]. But it turns out, in our controller, we were actually doing a side effect on that particular type of object if it were the case. So, after it was set to an instance variable, we called another method that essentially overwrote all of its associations and really changed the way that you would interact with that method, right? And that was the source of the bug is that we were expecting the associations to return what we, you know, thought it would, but this side effect was very subvertly changing that behavior. JOËL: Would it be fair to call this a classic mutation bug? STEPHANIE: Yeah. I didn't know there was a way to describe that, but that sounds exactly right. It was a classic mutation bug. And I think the assumption that I was making was that the controller code was, hopefully, just pretty straightforward, right? I was thinking, oh, it's just rendering plain text, so not [laughs] much stuff could really be happening in there, and that it must be the method in question that was causing the issues. But, you know, once I had to revisit that assumption and took a look at the controller code, I was like, oh, that is clearly incorrect. And from there, I was able to spot some, you know, suspicious-looking lines that led me to that line that did the mutation and, ultimately, the answer to our mystery. JOËL: Was the mutation happening directly in the controller? Or was this a situation where you're passing this object to a method somewhere, and that method, you know, in another object or some other file is doing the mutation on the record that you passed in? STEPHANIE: Yeah, that's a great question. I think that could have been a very likely situation. But, in this particular case, it was a little more obvious just in the controller code, which was nice, right? Because then I didn't have to go digging into all of these other functions that may or may not be the ones that is doing the mutation. But the thing that was really interesting is that it seems like that method that does this mutating is pretty key to the type of object that we're working with, as in most places it's used, that mutation happens. And yet, it's kind of separated from the construction of that object. And I was, I think, a little bit surprised that it wasn't super obvious that throughout the application, this is the way that we treat this special object. And I had wished that maybe that was a bit more cohesive or that it was kind of clear that this is how we use this in our domain. And it was, like, lacking that bit of clarity around how things are used in practice as opposed to trying to keep those in isolation. JOËL: Yeah. Because now you have sort of two different diverging use cases for using this object that are incompatible, one that's trying to use the object as is and the other that's depending on this mutation. Now you can't have both. STEPHANIE: Right. As far as I can tell, in most cases, you know, we're using it with a mutation, and maybe there is a good reason for those ideas to be separate. But it certainly did not make my life easier trying to solve this particular bug. JOËL: I'm hearing you mention the idea of ideas being separate; definitely kind of triggers some pathways in my modeling brain, where I'm already thinking, oh, maybe this should be a decorator, or maybe this is just a straight-up transformation. We just have a completely different kind of object rather than mutating the underlying record. STEPHANIE: Yeah, definitely. I think there could have been some alternative paths taken. At the time, that was kind of decided as the way forward for how to treat this particular domain object. So, that's my fun, little mystery where I got to, you know, play the detective role for a bit. Joël, what's new in your world? JOËL: So, earlier this year, on an episode of The Bike Shed, I mentioned that I was experimenting with a bookmark manager to kind of keep track of articles that I find are helpful that I might want to reference later on. I wasn't sure if it was going to be worthwhile and mentioned that I'd report back. I'm happy to report that it is working very well for me. So, the tool is Raindrop.io. They have an app. They have a website. And I have been sort of slowly filling it with some of my most commonly referenced articles. I had pulled some in initially, and then kind of over time, when I find myself referencing an article using my old-fashioned approach, which was just remember the keywords in the title and Google them, now I'll do that, link the article to someone else, and then add it to Raindrop so that the next time I'm starting to look for things, I have these resources available. And I try to curate a little bit by doing things like tagging them and categorizing them so that when I need references for something, I don't just have to go through my personal memory and be like, oh yeah, what articles do I have on data modeling that I think might be a good fit here? Instead, I can just go to the data modeling section of Raindrop and be like, oh yeah, these five are, like, my favorites that I link to all the time. STEPHANIE: Wow. We did a whole episode on how to search recently. And we totally forgot to mention things like bookmark managers or curating your own little catalog of go-to articles. In some ways, now you have to search within your bookmark manager [laughs]. JOËL: That's true. Sometimes, it's searching if I'm looking for a particular article, and sometimes, it's more browsing where I'm looking at a category, or a tag, or something like that, which maybe would have been another interesting distinction to explore on the How to Search episode. I do want to give a shout-out to the most recent article that I looked up in my bookmark manager here, Railway-Oriented Programming. It's an article on how to deal with pieces of code that can error and how to sort of compose those sorts of methods. So, you now have a whole sort of chain of different functions that can error or not in different sorts of ways. And it uses this really powerful metaphor of railway with different types of junctions and how you might try to, like, fit them all together so that everything connects nicely. And it's just a really beautiful metaphor. And I was doing some work on error handling, in particular, and I wanted to reference something and that was a great resource for that piece of work. STEPHANIE: Very cool. I'm really intrigued. I love a good metaphor. I am curious: is this programming language and framework agnostic and not about Rails? JOËL: Actually, so this is written on an F# blog. So, the code is all in F#. And it leans a little bit into some functional programming concepts, but the metaphor is more generic. So, it's a really fun way to think about when you're programming, and you're not just going through the happy path. But what are all the side branches that you might have to deal with, and how do those side branches come back into the flow of your program? STEPHANIE: Very cool. I can also see some really excellent visuals here if you were to use this metaphor as a way of understanding complexity. JOËL: Absolutely. In fact, this article has some pretty amazing visuals, so strong recommend. We'll link it in the show notes. STEPHANIE: So, a few episodes ago, we talked about code ownership at scale because my client project that I'm working on is for a company with hundreds of developers. So, it's quite a big codebase, quite a big team. One of the main issues that I, at least, struggle with on a day to day is flaky tests in CI. When I, you know, I'm wanting to merge a change, I often have to run the test suite a few times to get to green and be able to merge and deploy. And this is an interesting topic to me because when you're really trying to just get your changes through and mark that ticket as done, it's very tempting to just hit that, you know, retry button and let it sit and just hope for the best, as opposed to maybe investigate a little further about why that test was flaking and see if there's something that you could do about it. So, I wanted to talk to you about the idea of making the right thing easy or how, at both a team level and an individual level, we can set ourselves and our team up for success rather than shoulder this burden [laughs] and just assume that things are the way they are. JOËL: That's a really powerful question. Because I think by default, oftentimes, the less helpful thing is the path of least resistance, so, in this case, hitting that rerun button on a test suite, which I've absolutely done. But there's a lot of other situations in our work where, just sort of by default, the path of least resistance is the thing that's maybe less helpful for the team. STEPHANIE: Ooh, I noticed that you kind of reframed what I said. I was using the term, you know, the right thing, but you then reworded it into the helpful thing. And that actually gets me thinking about these words are kind of subjective, right? What is helpful to someone could be different to what's helpful to someone else. And I'm kind of curious about your definition of the helpful thing. JOËL: Yeah, I mean, sometimes it's very easy to sort of bring absolutes and [inaudible 11:26] judgments to code, you know, when we talk about writing good code, and being good programmers, being good at our jobs, not doing the bad things. And I think that sort of absolutism sometimes can, like, be very restrictive, and kind of takes us down paths that are not optimal for ourselves, for our teams, for our products. So, I'd like to think a little bit more relativistically have a little bit more of elasticity in the way that we formulate some of these ideas. STEPHANIE: Yeah. I really like that reframing, and I appreciate the nuance there. I think for me, when I think of doing the helpful thing, I'm hoping to ease the day-to-day workflow for other developers because that also includes myself, right? Like, I've certainly been there feeling frustrated or just kind of tired of retrying [laughs] the test suite over and over again. I'm also thinking about helpful, as in what will be helpful for future developers regarding the product? And can we make it robust now so that we're not dealing with bug reports later for things that we maybe we're trying to throw under the rug or just kind of glance over? Do you have any other guiding principles around what is helpful and what's not? JOËL: I think that the time horizon you mentioned is really interesting because you have to balance sometimes short-term value versus kind of long-term. And is it worth it to maybe not fix that flaky test today so that we can ship as soon as possible? Or is it worth investing a little bit of time today so that tomorrow or next week is better? If you're a solo developer on a tiny project, that might be of personal benefit only. But on a larger team, you know, that might benefit not just you but a larger amount of people. STEPHANIE: I just imagined the trolley problem [laughs] a little bit about, you know, the future developers and whose lives, not lives but whose happiness, the developer happiness you'll save [laughs] when you're on that track and making the decision about benefit now versus benefit later. JOËL: No connection to railway-oriented programming, by the way. STEPHANIE: I am really interested in also talking about barriers to doing the helpful thing or taking that extra step, right? Because I think identifying those barriers is really important to then, hopefully, break them down so that we are creating that path of least resistance. JOËL: That's interesting that you mentioned these as barriers because I think, in my mind, I was thinking about the same idea but from, like, a completely mirror perspective, the idea of incentives. Why do incentives push you in one way versus the other? STEPHANIE: I like that a lot. I think maybe there are, like, two different levers, right? Or maybe they are two sides of the same coin, where you do have incentive, and then you also have things that disincentivize you. JOËL: This reminds me a little bit of the idea of the tragedy of the commons. So, in the case of flaky tests, everybody as a whole on your project has a worse experience. And project velocity slows when there are flaky tests. But you, as an individual developer, are incentivized to ship features quickly and efficiently. And the fastest way you can get your individual feature to production is by hitting that rerun button. Even though, collectively as a whole, every time we do that, instead of fixing the flakiness, we're adding a tiny, little bit of extra slowness that will accrete over time. STEPHANIE: Yeah. It's kind of difficult to imagine really the negative impact that it's having collectively, right? You're kind of like, oh, I'm feeling this pain, but you're not always, like, really hearing about it from others, and we might just be silently suffering together [laughs]. I do think that once it's been identified as like, oh, like, we're all actually, like, really impacted by this, okay, great, let's make it a priority. And so, now, let's say I am slightly incentivized to go and investigate the flakiness of a test rather than hit the rerun button this time around. I am wanting to talk about those barriers I was referring to a little bit because I've been in this position where I'm like, okay, like, I have some extra time today. So, why don't I look into this? But then I go down that path, and now I'm looking at a test written by someone many years ago, you know, I don't know this person, and I don't know this domain. I don't know who to talk to to figure out even where to start. I may or may not feel equipped with the right tools to be able to address it. And then, I think the biggest challenge is not feeling like it matters, right? Once I'm hitting this barrier, I'm like, is it worth the effort? At that point, maybe a little bit demoralized because, well, this is just one, and we have so many other flaky tests, like, what's one more? JOËL: That's really interesting that you mentioned that sort of morale factor because it's absolutely the case on every flaky test suite I've seen. I think that kind of points to almost, like, an exponential cost to ignoring the problem. If someone fixed it early, yeah, it's slightly annoying, but you get it done. You fix it, and then you move on. When it feels like there's now this insurmountable pile of these and that any work you do here doesn't bring you any closer to the goal because it's effectively infinite, yeah, now, there is no incentive at all to do that work. STEPHANIE: So, to avoid that, we talked about incentives, right? And I'm kind of curious: what ways have you seen or experienced that did make you feel motivated to take that extra step or at least try to avoid that point of thinking that nothing matters? [laughs] JOËL: So, I'm going to start with, I think, what's maybe a classic developer answer, and I'm curious to get your thoughts on it because I think I have very mixed feelings about this. The idea of programmer discipline—we just need to kind of take more pride in our craft and pursue excellence, choose to do the right thing, even when it's hard every day. Because I hear a lot of that in our communities. How do you feel about that sort of maybe a bit of a mindset change? And how effective has that been? STEPHANIE: Whoa, yeah, that's a really great point because I think I also feel quite conflicted about it. Because sometimes I can find it in myself to be, like, you know, I have the energy today to want to uphold, like, a certain level of quality that would make me feel good about doing my best work. And then, there are other days where I am, you know, just tired, [laughs] or feeling a little bit lazy, feeling just not confident that it will be worth it. Because there's also, I think, some external forces, right? I've certainly been in the position where we were only rewarded or celebrated for shipping fast. That was the praise we were getting at retros. But then that actually really disincentivized me from wanting to do the helpful thing when the time came, right? When I'm in my development process, and I'm at, like, that crossroads. Because I'm like, well, I've been trying to do the right thing, but, like, no one is celebrating me for it. What if it takes away time from doing the thing that is considered successful? And, like, does it have an impact on me and my job? So, you can, you know, kind of go down that spiral pretty quickly. And, in that case, like, no amount of personal, like, individual [laughs] feelings of responsibility can really overcome those consequences if, like, you're working on a team where that is just simply not valued, and there are other people who have authority to impart consequences, I suppose. JOËL: Yeah. It's, you know, you have that maybe some amount of personal motivation. You feel like you're swimming upstream. And so, maybe the question then is, how do we reorient maybe some of the incentive structures in a team to try to make it so that if you are, let's just say, chasing some of those extrinsic rewards and you're trying to get praise from your teammates, or move forward in your career, whatever it is that is rewarded and valued on your team, how can that be harnessed to push people in a direction to get some of these extra tasks done? STEPHANIE: Yeah. I will say, though, it is a little bit of both. And I think that was maybe why we're both kind of conflicted about it. Because on the individual level and, in general, knowing what my values are and, like, wanting to do good work and uphold quality, there are times where I don't always behave according to those values. Like I said, I am feeling tired, or maybe it's, like, almost 5:00 o'clock, and I just want to, you know, push my thing [laughs] so I can go and go on with my day. What has helped me is having an accountability buddy. Maybe it's in code review, or maybe it's when I'm pairing, or maybe just talking about a problem that we're facing, right? And I might get into that sort of lizard-brain mentality of just wanting to do the easy thing. But as soon as someone else points it out or is, like, you know, like, "That's not quite aligning with what I know your, like, hopes and goals are for this project or how you want to do your work," usually, that's enough to be like, "Yeah, you're right." [laughs] And I'll take another pass at it. JOËL: And I think we've kind of come back full circle here in that you mentioned that sort of the lizard brain side of you wants to just do the easy thing with the implication that, in this case, the easy thing is the thing that's maybe not useful to the team long term. What if we could restructure things a little bit so that the easy thing was the most beneficial thing for the team? And now you're not having to use discipline to fight the lizard brain side of you, but you're actually working with it. One thing I've seen teams do with flaky tests is to not necessarily fix them immediately. Like, maybe you do rerun them, but when they happen, create a ticket for them and put them into the planning board. And so, now, these are things that get prioritized. They're things that might be fairly quick to do. So, it might be a fun, like, fast ticket for someone to pick up at the end of the week. It now counts towards velocity if tracked, so people, hopefully, get rewarded for doing that work. Is that something that you've seen? And how effective do you think that is in maybe making fixing flaky tests easier thing for a team? STEPHANIE: Yeah, that is actually something that we are doing on my team right now, and I think it's great. I like the idea of tracking it, right? Because then you could also see over time, like, whether we have been getting better at reducing flaky tests, you know, then it's also really clear when someone is preoccupied with that work, and they don't get assigned something else. One way that I've seen it not work as well as we hoped is when other work consistently gets prioritized over those flaky test tickets, and, you know, sometimes it happens. I think that's also information, though, about the team and how the team is spending its time compared to how the team thinks it should be ideally spending its time where, you know, we can say all we want, like, yes, like, we really want to make sure our test suite is robust. But when other things are consistently getting prioritized over it, then you can point to it and say, do we actually believe this if we're consistently not behaving according to that belief? I found that challenging to have that conversation. But I do think that the concreteness of adding it to our workload for a given period of time is at least providing information rather than it being things that, like, developers are doing one-off or kind of just on their own time. JOËL: Another solution that I've seen people do, and this is a classic developer solution, is tooling. If you have better tooling around a particular problem, sometimes you can shift that cost, that time of work it takes so that it's easier to do the best thing rather than to not...or at least make it easy enough that it's less of a big decision, like, oh, do I really want to invest that much work into something? And a classic example of this, I think, is when you're trying to get into more of a test-driven development workflow. Having a test suite that's fast and, really importantly, having a near-instant way to run a test from your code editor makes a big difference in terms of adopting that workflow. Because if the cost of running a test is too high, then yeah, the easy path is to just say, you know what? I'm not going to run a test. I'm going to just run it once at the end after I've written 100 lines of code or an entire feature. And now I am not getting the benefits of TDD. And that might kind of get into a negative cycle where because I'm not seeing the benefits, I do it even less. And then eventually, I'm just, like, you know what? Forget this whole thing. STEPHANIE: I think that also applies to testing in general, where if it, you know, is feeling really challenging. I have definitely seen people start to get into that mindset of, is this worth my time to do at all? And it's a very slippery slope, I think. That almost makes me think about, like, okay, like, what are some other ways to lift that task up and to elevate it into something that's worthy of saying, like, "Hey, like, that was really hard, and you did a great job. And that was really awesome that you persevered through that challenging thing." Sharing the pain points is really important, not only to, like I mentioned earlier, to, like, communicate that, oh, maybe, like, more people than you think are going through the same thing, but also to be able to identify when someone went out of their way to do the helpful thing and seeing that someone was willing to do it because, for them, being helpful is important. When I see someone on my team take on kind of a difficult task to make things easier for others and then share about it, I feel really inspired because I think, wow, like, that could be me as well. You know, there's that saying that many hands make light work. And I also think that's true of tackling these kinds of barriers, where if we all feel this collective responsibility or, like, wanting to help out the group, it ends up literally being easier. JOËL: I think something I'm hearing here as well is the value of giving praise. If somebody goes out of their way to make life easier for the rest of your team, give them a shout-out, whether that's in your team's Slack channel, maybe it's at an all-hands meeting, and you shout out some work that they've done or, you know, you put their name on a slide in your slide deck at some point, or whatever it is the mechanism within your team. Having a way to shout out people who've done some of this work that can be sometimes a little bit thankless is a great way to motivate seeing more of that. STEPHANIE: Yeah. I was just thinking that it can be really powerful because, like you said, a lot of it is thankless, but also, we may not even realize the impact it's having on others until you give that shout-out and express, like, "Wow, like, that change, you know, I've been bothered by this issue for so long and, you know, that really made an impact on me," just keeping that cycle of gratitude going. JOËL: So, I think we've kind of identified three maybe main areas of ways where you can help to incentivize these behaviors. You can do it through kind of process. We talked about the example of pulling the flaky tests as actual cards to be worked through on a board. It can be technical by introducing some tooling that makes it much easier to do the work that you're trying to do. And it can be personal by praising people, preferably in public, for taking that extra step. And I think all three of those can be part of a strategy to make it easier or more attractive for people to do work that benefits the team as a whole, even if they don't see an immediate return to that on a per-day level. STEPHANIE: Yeah. I like that we kind of talked about these three different categories. And people in all different types of roles can, hopefully, take something from what we've shared, right? If you are a manager or leader of a team, maybe you can investigate your processes. If you're an individual contributor and you notice your colleague doing something that you, you know, kept meaning to but just didn't have time for, recognize that work. It really does take a holistic approach, but I think an impact can be made at every level. JOËL: Agreed. I think for managers and more senior team members, that's really almost, like, part of their job description is to think about these kinds of things. How can we incentivize this work? How can we shift the team in a particular direction? There's a particular onus on them to do this right, to think about this, to model some of this behavior. STEPHANIE: Yeah, absolutely. JOËL: For someone who's really senior on a team also, they're often the ones who are tasked or who maybe take the initiative to build some of this more complex tooling so that these tasks are easier for more junior people. Maybe that's tinkering with some things and building an editor plugin that makes it easier to do some work. Maybe it's building a Rails generator so that the proper files get generated that maybe people wouldn't think to have when they're building certain work. Maybe it's building an RSpec matcher to make it easier for people to test some of the nuances of what we're hoping to do, catching some of these edge cases. Whatever it is, sometimes there are things that the more junior members of our teams aren't aware of, and having a senior person take time out of their day to build these things so that now the entire team can be more productive can be a really helpful thing to do. STEPHANIE: Yeah, that's a great point. And I think that also comes from having a pulse on what people are struggling with, right? So, you know, oh, it would be good to invest my energy into building a script to make this manual process easier because I keep hearing about people having issues with it or it being a challenge. So, I would even recommend posing the question of, like, how do people feel about being able to fix that flaky test, right? Like, is it intimidating? What are those barriers? Because your team knows best about what that experience is like. And if that is not something on your radar, maybe there are opportunities to incorporate it into where you're evaluating team morale and happiness. On that note, shall we wrap up? JOËL: Let's wrap up. STEPHANIE: Show notes for this episode can be found at bikeshed.fm. JOËL: This show has been produced and edited by Mandy Moore. STEPHANIE: If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter. STEPHANIE: Or reach both of us at hosts@bikeshed.fm via email. JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week. ALL: Byeeeeeeee!!!!!!! ANNOUNCER: This podcast is brought to you by thoughtbot, your expert strategy, design, development, and product management partner. We bring digital products from idea to success and teach you how because we care. Learn more at thoughtbot.com.

Joël shares he has been getting more into long-form reading. Stephanie talks about the challenges she faced in a new project that required integrating with another company's system. Together, they delve into the importance of search techniques for developers, covering various approaches to finding information online. Domain Modeling Made Functional (https://pragprog.com/titles/swdddf/domain-modeling-made-functional/) Episode on heuristics (https://www.bikeshed.fm/398) Episode on specialized vocabulary (https://www.bikeshed.fm/356) Episode on discrete math (https://www.bikeshed.fm/374) Joël’s discrete math talk at RailsConf (https://www.youtube.com/watch?v=wzYYT40T8G8) Dash (https://kapeli.com/dash) Alfred (https://www.alfredapp.com/) Indiana Jones and the Crypt of Cryptic Error Messages (https://thoughtbot.com/blog/indiana-jones-and-the-crypt-of-cryptic-error-messages) Browser History confessional by Kevin Murphy (https://www.youtube.com/watch?v=R7LkHjJdH9o) Transcript: STEPHANIE: Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Stephanie Minn. JOËL: And I'm Joël Quenneville. And together, we're here to share a bit of what we've learned along the way. STEPHANIE: So, Joël, what's new in your world? JOËL: Something I've been trying to do recently is get more into long-form reading. I read quite a bit of technical content, but most of it are short articles, blog posts, that kind of thing. And I've not read, like, an actual software-related book in a few years, or at least not completed a software-related book. I've started a few chapters in a few. So, something I've been trying to do recently is set aside some time. It's on my calendar. Every week, I've got an hour sit down, read a long-form book, and take notes. STEPHANIE: That's really cool. I actually really enjoy reading technical stuff in a long-form format. In fact, I was similarly kind of trying to do it, you know, once a week, spend a little bit of time in the mornings. And what was really nice about that is, especially if I had, like, a physical copy of the book, I could close my computer and just be completely focused on the content itself. I also love blog posts and articles. We are always talking on the show about, you know, stuff we've read on the internet. But I think there's something very comprehensive, and you can dig really deep and get a very deeper understanding of a topic through a book that kind of has that continuity. JOËL: Right. You can build up a larger idea have more depth. A larger idea can also cover more breadth. A good blog post, typically, is very focused on a single thing, the kind of thing that would really probably only be a single chapter in a book. STEPHANIE: Has your note-taking system differed when you're applying it to something longer than just an article? JOËL: So, what I try to do when I'm reading is I have just one giant note for the whole book. And I'm not trying to capture elements or, like, summarize a chapter necessarily. Instead, I'm trying to capture connections that I make. So, if there's a concept or an argument that reminds me of something perhaps similar in a different domain or a similar argument that I saw made by someone else in a different place, I'll capture notes on that. Or maybe it reminds me of a diagram that I drew the other day or of some work I did on a client six months ago. And so, it's capturing all those connections is what I'm trying to do in my notes. And then, later on, I can kind of go back and synthesize those and say, okay, is there anything interesting here that I might want to pull out as an actual kind of idea note in my larger note-taking system? STEPHANIE: Cool, yeah. I also do a similar thing where I have one big note for the whole book. And when I was doing this, I was even trying to summarize each chapter if I could or at least like jot down some takeaways or some insights or lines that I like felt were really compelling to me. And, like, something I would want to, in some ways, like, have created some, like, marker for me to remember, oh, I really liked something in this chapter. And then, from there, if I didn't capture the whole idea in my note, I knew where I could go to revisit the content. JOËL: And did you find that was helpful for you when you came back to the book? STEPHANIE: Yeah, it did. I usually can recall how, like, I felt reading something. You know, if something was really inspiring to me or really relatable, I can recall that, like, I had that experience or emotion. And it's just, like, trying to find where that was and that this is a system that has worked well for me. Though, I will say that summarizing each chapter did kind of remind me of, like, how we learned how to take notes in school. [laughs] And I think, you know, middle school, or whatever, I recall a particular note-taking format, where you, you know, split the page up into, like, an outline with all the chapters, and you tried to summarize it. And so, it did feel a little bit like homework [laughs]. But I can also see the value in why they taught me how to do that. JOËL: I was recently having a conversation with someone else about the idea of almost, like, assigning yourself the college-style essay question after finishing a book to try to synthesize what you learned. STEPHANIE: Whoa, that's really cool. I can see how that would really, like, push you to synthesize and process what you might have just consumed. And, also, I'm so glad I'm not in school anymore [laughs] so that I don't have to do that on a regular basis. [laughs] I'm curious, Joël, what book are you reading right now? JOËL: I've been reading Domain Modeling Made Functional, which is a really interesting intersection between functional programming, Domain-Driven Design (DDD), and a lot of interesting kind of type theory. And so, that sort of intersection of those three Venn diagrams leads to this really fascinating book that I've been going through. And I think it connects with a lot of other things that I've been thinking about. So, I'll be reading and be like, oh, this reminds me of this concept that we have in test-driven development. Or this reminds me of this idea that we do when we do a product design sprint. And this reminds me of this principle from object-oriented design. And now I'm starting to make all these really interesting connections. STEPHANIE: Awesome. Well, I hope to hear more about what you've learned or kind of what you're thinking about going through this book in future episodes. JOËL: This is not the last time we hear about this book, I'm pretty sure. So, Stephanie, what's new in your world? STEPHANIE: So, I have a little bit of a work update to share. So, lately, I've been brought in to work on a feature that is integrating with another company's system. And the way that I was brought into this work was honestly just being assigned a task. And I was picking up this work, and I was kind of going through the requirements that had been specked out for me, and I was trying to get started. And then, I realized that I actually had a lot of questions. It just wasn't quite fully fleshed out for the level of detail that I needed for implementing. And for the past couple of weeks, we've been chatting in Slack back and forth as I tried to get some of my questions answered. They are trying to help me, but also the things that I'm saying end up confusing them as well. And then, I end up having to try and figure out what they're looking for in order to properly respond to them. And I had not met these people before. These are folks from that other company. And, you know, I'd only just seen their little Slack profile pictures. So, I didn't know who they were. I didn't know what role they had and kind of, like, what perspective they were coming to these conversations from. And after a while, I was feeling a little stressed out because we just kept having this back and forth, and not a lot of answers were coming to fruition. And I really ended up needing the nudge of the manager on my client team to set up a meeting for us to all just talk synchronously. And I think I had...not that I had been avoiding it necessarily, but I guess I was under the impression that we were at the point where we could just, you know, shoot off a question in Slack and that there would be a clear path forward. But the more we kept pulling on that thread, the more I realized that, oh, like, we have a lot of ambiguity here. And it really helped to meet them finally, not in person but, like, over a video call. [laughs] So, this happened yesterday. And, you know, even just, like, going around doing introductions, like, sharing what their role was at the company helped me just understand, like, who I was talking to. You know, I realized, oh, like, the level of technical details that I had been providing was maybe too much for this group. And I was able to have a better understanding of what their needs were, like hearing kind of the problem that they had on their end. And I realized that, oh, like, they actually aren't going to provide me the details for implementation that I was looking for. That's up to me. But at least now I know what their higher-level needs are so that I can make the most informed decisions that I can. JOËL: Fascinating. So, you thought that this was going to be, like, the technical team you're going to work with. And it turns out that this was not who they were. STEPHANIE: In some ways. I think I thought by providing more technical details that would be helpful, but it ended up being more confusing for them. And I think I was similarly kind of frustrated because the ways that I was asking questions or communicating also wasn't getting me the answers that I needed as well. But I felt really great after the meeting because I'm like, wow, you know, it doesn't have to be as stressful. You know, when you start getting into that back and forth on Slack, at least I find it a bit stressful. And it turns out that the antidote to that was just getting together and getting to know each other and hashing out the ambiguity, which does seem to work better in a more synchronous format. JOËL: Do you have kind of a preference for synchronous versus asynchronous when it comes to communication? STEPHANIE: That's a good question. I think it's kind of a pendulum for me. I'm in my asynchronous communication is a bit better for me right now phase, but only because I am just so burnt out on meetings a lot of the time that I'm like, oh, like, I really don't want to add another meeting to my calendar, especially because...I amend my statement; I'm burned out of meetings that don't go well. [laughs] And this meeting, in particular, was different because, you know, I realized, like, oh, like, we are not on the same page, and so how can we get there? And kind of making sure that we were focused on that as an agenda. And I found that ultimately worked out better than the async situation that I was describing, which I'm thinking now, you know when things aren't clear, text-based communication certainly does not help with that. JOËL: So, meetings, sometimes they're actually good. STEPHANIE: Yeah, that's my enlightened discovery this week. JOËL: So, this episode is kind of a special one. We've just hit 400 episodes of The Bike Shed. So, this is episode number 400. It's also my 50th Episode as a co-host. STEPHANIE: Right. That's a huge deal. 400 is a really big number. I don't know if I've ever done 400 of anything before [laughs]. JOËL: The Bike Shed has been going on for almost ten years now. The first episode up on the website is from October 31st, 2014, so just about nine years from that first episode. STEPHANIE: Wow. And it's still going strong. That's really awesome. I think it's really special to be a part of something that has been going on for this long. And, I don't know, maybe there are still listeners today from back in 2014. I would be really excited to hear if anyone out there has been listening to The Bike Shed throughout its whole lifespan. That's really cool. JOËL: Looking back over the last 50-ish episodes you and I have done, do you have a favorite episode that we've recorded? STEPHANIE: This may be a bit of recency bias. But the episode that we did about Software Heuristics I really enjoyed. Because I think we got to bring to the table some of the things we believe and the way we like to do things and kind of compare and contrast that with each other. And I always find people's processes very fascinating. Like, I want to know how you think and where your brain is at when you approach a problem. So, I really enjoyed that topic. What about you? Do you have any highlight episodes? JOËL: I think there's probably two for me. One is the episode that you and I did on Specialized Vocabulary. I think this really touched on a lot of really interesting aspects of writing software that's going to scale, software that works for a team, and also kind of personal growth and exploration. The second one that I think was really fun was the episode I did with Sara Jackson as a guest talking about Discrete Math because that's an episode that I got really excited about the topic. And right after recording the episode, it was the last day of the call for proposals for RailsConf. And I just took that raw excitement, put together a proposal, hit submit before the deadline. And it got accepted and got turned into a talk that I got to give on stage. So, that was, like, just a really fun journey from exciting episode with Sara and then, like, randomly turned into a conference talk. STEPHANIE: That's awesome. That makes me feel so happy. Because it just reminds me about how the stuff we talk about on the show can really resonate with people, you know, enough to become a conference talk that people want to attend. And I also really like that a lot of the topics we've gotten into in the past 50 episodes when we've taken over the show have been a bit more evergreen and just about, you know, the software development experience and a little bit less tied to specific news within the community. Speaking of evergreen topics, today, I wanted to discuss with you an evergreen software skill, and that is searching or Search-Driven Development, even if you will. JOËL: Gotta always get that three-letter acronym, something DD. STEPHANIE: Yeah. I am really curious about how we're going to approach this topic because a lot of folks might joke that a big part of writing software is knowing what to Google. Do you agree with that statement or not? JOËL: Yes and no. There's definitely value in knowing what to Google. It really depends on the kind of work that you're doing. I find that I don't Google that much these days. There are other tools that I use when I'm particularly, like, searching through documentation, but they tend to be less sort of open-ended questions and more where it's like, oh, let's get the actual documentation for this particular class or this particular method from the standard library. STEPHANIE: Oh, interesting. I like that you pointed out that there are different scopes of things you might want to search for. So, am I hearing correctly that when you have something specific in mind that you are just trying to recall or wanting to look up, you know, you're still using search that way, but less so if you are trying to figure out how to approach solving a problem? JOËL: So, oftentimes, if I'm working with a language that I already have familiarity with or a framework that I have familiarity with, I'm going to lean on something more specific. So, I'm going to say, okay, well, I don't exactly remember, like, the argument order for Enumerable's inject method. Is it memo then item, or item then memo? So, I'll just look it up. But I know that the inject method exists. I know what it does. I just don't remember the exact specifics of how to do that. Or maybe I want to write a file to disk, and I don't remember the exact method or syntax to do that. There are some ways that you can do it using a bunch of instance methods. But I think there's also a class method that allows you to kind of do it all at once. So, maybe I just want to look up the documentation for the file class in Ruby and read through that a little bit. That's the kind of thing where I suppose I could also Google, you know, how to save file Ruby, something like that. But for those sorts of things where I already roughly know what I want to do, I find it's often easier just to go directly to the docs. STEPHANIE: Yeah, yeah, that's a great tip. And I actually have a little shortcut to share. I started using DuckDuckGo as my search engine in the past year or so. And there's this really cool feature called Bangs for directly searching on specific sites. From my search bar, I can do, let's say, bang Rails and then my query. And it will search directly the Rails Guides website for me instead of, you know, just showing the normal other results that might come up in my regular search engine. And the same goes for bang Ruby doc. That one shows ruby-doc.org, which is my preferred [laughs] Ruby documentation website. I've really been enjoying it because, you know, it just takes that extra step out of having to either navigate to the site itself first or starting more broadly with my search engine and then just scrolling to find the site that I'm looking for. JOËL: Yeah. I think having some kind of dedicated flow helps a lot. I have a system that I use on my machine. It is Mac-specific. But I use a combination of the application Dash and the application Alfred. It allows me, with just a few keyboard shortcuts, to type out language names. So, I might say, you know, Ruby inject, and then it'll show me all the classes that have that method defined on it, hit Enter, and it pops up the documentation. It's downloaded on my machine, so it works offline. And it's just, you know, a few key presses. And that works really nicely for me. STEPHANIE: Oh, offline search. That's really nice. Because then if you're coding on a plane or something, then [laughs] you don't have to be blocked because you can't look up that little, small piece of information you need to move forward. That's very cool. JOËL: That is really cool. I don't know how often I've really leaned into the offline part of it. I don't know about you; I feel like I don't code on airplanes as much as I thought I would. STEPHANIE: That's fair. I also don't code on airplanes, but the idea that I could is very compelling to me. [laughs] JOËL: Absolutely. So, that's the kind of searches that I tend to do when I'm working in a language that I already know, kind of a day-to-day language that I'm using, or a framework that I'm already pretty familiar with. And this is just looking at all the things I haven't gotten to the point where I've fully memorized, but I have a good understanding of. What about situations where maybe you're a little bit less familiar with? So maybe it's a new framework, or even, like, a situation where you're not really sure how to proceed. How do you search when there's more uncertainty? STEPHANIE: Yeah, that's a good question. I do think I start a bit naively. The reason that we're able to be more specific and know exactly where to go is because we've built up this experience over time of scrolling through search results and clicking, you know, maybe all of them on the first page, even, and looking at them and being like, oh, like, this is not what I want. And then, seeing something else, it's like, oh, this is more helpful and kind of arrived at sources that we trust. And so, if it's something new, I don't really mind just going for a basic search, right? And starting more broadly might even be helpful in that process of building up the experience to figure out which places are reputable for the thing that I'm trying to figure out. JOËL: Yeah, especially when there's a whole new landscape, right? You don't really know what are the places that have good information and the ones that don't. For some things, there might be, like, an obvious first place to start. So, recently, I was on a project where I was trying to do an integration between a Rails app and a Snowflake data warehouse. And so, the first thing I did—I'm not randomly Googling—I went to the Snowflake website, their developer portal, and started reading through documentation for things. Unfortunately, a lot of the documentation is a bit more corporatey and not really helpful for Ruby-specific implementation. So, there's a few pieces that were useful. There were some links that they had that sent me to some good places. But beyond that, I did have to drop to Google search and try to find out what kinds of other things the community had done that could be helpful. Now, that first pass, though, did teach me some interesting things. It gave me some good keywords to search for. So, more than just Ruby plus Snowflake or something like that like, I knew that I likely was going to want to do some kind of connection via ODBC. So, now I could say, okay, Ruby plus ODBC integration, or Ruby plus ODBC driver and see what's happening there. And it turns out that one of the really common use cases for ODBC and Ruby is specifically to talk to Snowflake. And one of the top results was an article saying, "Hey, here's how you can use ODBC to get your Rails app to talk to Rails." And then I knew I struck gold. STEPHANIE: That's really cool. The thing that I was picking up on in what you were saying is the idea of finding what is most relevant to you. And maybe that is something that the algorithm serves you because, like, it's, like, what a lot of people are searching for, you know, a lot of people are engaging with, or matching with all these keywords that you're using. My little hack that I've been [chuckles] using is to use Slack and lean on other people who have maybe a little more, even just, like, a little more experience than me on the subject, and seeing, like, what things they're linking to, and what resources they're sharing. And I've found that to be really helpful as a place to start. Because, at that point like, my co-workers are narrowing down the really broad landscape for me. JOËL: I really like how you're sort of you're redefining the question a little bit here. And that, I think, when we talk about search, there's almost this implicit assumption that search is going to be searching the public internet through Google or some other alternative search engine. But you're talking about actually searching from my private corpus of data, in this case, either thoughtbot or maybe the client's Slack conversations, and pulling up information there that might be much more relevant or much more specific to the work that you're trying to do. STEPHANIE: Yeah. In some ways, I like to think of it as crowd-sourced but, like, a crowd that I trust and, you know, know is relevant to me and what I'm working on. I actually have a fun fact for you. Did you know that Slack is actually an acronym? JOËL: No, I did not know that. What does it stand for? STEPHANIE: It stands for Searchable Log of All Communication and Knowledge. JOËL: That is incredibly clever. I wonder, is this the thing where they came up with that when they made the original name? Or did someone go back later on, you know, a few years into Slack's life and was like, you know what? Our name could be a cool acronym; here's an idea. STEPHANIE: I'm pretty sure it was created in Slack's early days. And I think it might have even helped decide that Slack was going to be called Slack as opposed to some of the other contenders for the name of the software. But I think it's very accurate. And that could just be how I use Slack. I'm a very heavy search power user in Slack. [laughs]. So, I find it very apt. You know, obviously, I use it a lot for finding conversations that happened. But I really do enjoy it as a source of discovery for a specific topic, or, you know, technical question or idea that I'm wanting to just, like, filter down a little bit beyond, like you said, the public internet. In fact, I have found it really useful for when you encounter errors that actually are specific to your domain or your app. Obviously like, you will probably be less successful searching in your search engine for that because it includes, you know, context from your app that other people in the world don't have. But once you are narrowing it down to people at your company, I've been able to get over a lot of troubleshooting humps that way by searching in Slack because likely someone within my team has encountered it before. JOËL: So, you mentioned searching for error messages in particular. And I feel like that is, like, its own, like, very specific searching skill separate from more general, like, how do I X-style questions. Does that distinction kind of line up with your mental map of the searching landscape? STEPHANIE: Yeah. I guess the way that I just talked about it now was potentially a bit confusing because I was saying instead of how you might search for errors normally, but I did not talk about how you might search for errors normally. [laughs] But specifically, you know, if I'm popping error messages into my search engine, I am removing the parts of the stack trace that are specific to my app, right? Because I know that that will only kind of, like, clutter up my query and not be getting me towards a more helpful answer as to the source of my issue, especially if the issue is not my application code. JOËL: Right. I want to give a shout-out to an article on the thoughtbot Blog with a wonderful name: Indiana Jones and the Crypt of Cryptic Error Messages by Louis Antonopoulos. All about how to take an error message that you get from some process in your console and how to make that give you results when you paste it into a search engine. STEPHANIE: I love that name. Very cool. JOËL: So, you've talked a little bit about the idea of searching some things that are not on the public internet. How do you feel about kind of internet knowledge bases, private wikis, that kind of thing? Have you had good success searching through those kinds of things? STEPHANIE: Hmm, I would say mixed success, to be honest. But that's because of maybe more so the way that a team or a company documents information. The reason I say mixed results is because, a lot of the time, the results are outdated, and they're no longer relevant to me. And it doesn't take that much time to pass for something to become outdated, right? Because, like, the code is always changing. And if, you know, someone didn't go and update the documentation about the way that a system has changed, then I usually have to take the stuff that I'm kind of seeing in private wikis with a bit more skepticism, I would say. JOËL: Yeah, I think my experience mirrors yours as well. Also, some private wikis have just become absolutely huge. And so, searches just return a lot of results that are not really relevant to what I'm searching for. The searching algorithms that these systems use are often much less powerful than something like Google. So, they often don't sort results in a way that are bringing relevant things up to the top. So, it's more work to kind of sift through all of the things I don't care about. STEPHANIE: Yeah, bringing up the size of a wiki and, like, all of the pages, that is a good point because I see a lot of duplicate stuff, but that's just, like, slightly different. So, I'm not sure which one I'm supposed to believe. One really funny encounter that I had with a private wiki, or actually it was, like, a knowledge base article that was for the internal team...it was documenting actually a code process. So, it was documenting in more human-readable terms, like the steps an algorithm took to determine some result. But the whole document was prefaced by, "This information came from an email that was sent way long ago." [laughs] JOËL: That's an epic start to a Wiki article. STEPHANIE: Yeah. And there was another really funny line that said, "The reason for this logic is because of a decision made by (This person's name.)," like a business decision that (some random person name). No last name either, so I have no idea [laughs] who they could be referring to and any of the, like, historical context of why that happened. But I thought it was really funny as just a piece of, like, an artifact, of, at the time, when this was written, that meant something to someone, and that knowledge kind of has been diluted [laughs] over the years. JOËL: Yeah, internal wikis, I feel like, are full of that, especially if they've had a few years to grow and the company has changed and evolved. So, now it's time for hot takes. STEPHANIE: Yeah, I'm ready for them. JOËL: We are now in the fancy, new age of AI. Is ChatGPT going to make all of this episode obsolete? STEPHANIE: I'm going to say no, but I'm also biased, and I'm not a ChatGPT enthusiast. I've said it on air. [laughs] I can't even say that I've used it. So, that's kind of where I'm coming from with all this. But I have heard from folks that, convenient as it may be, it is not always 100% accurate or successful. And I think that one of the things I really like about kind of having agency over my search is that I can verify, as a human, the information that I'm seeing. So, you know, when you're, like, browsing a bunch of Stack Overflow questions and you see, you know, all these answers, at least you can, like, do a little bit of, like, investigation using context clues about who is answering the question, you know, like, what experience might they have? If you encounter something on a blog post, for example, you can go to the about page on this person's blog and be like, who are you? [chuckles] And, like, what qualifies you to give this information? And I think that is really valuable for me in terms of evaluating whether I want to go down a path based on what I'm seeing. JOËL: So, I've played with it a tiny, little bit, so not enough to have a good sample size. And I think it can be interesting for some of those less constrained kind of how do I style questions. I'm not necessarily looking for, like, an exact code sample. But even if it just points me towards, oh, I need to be looking at this particular class in this standard library and read through that documentation to build the thing that I want. Or maybe it links me to kind of the classic blog posts that people refer to when talking about this thing. It's a good way sometimes to just narrow down when you're kind of faced with, you know, the infinity of the internet, and you're kind of like, oh, I don't even know where to start. It gives you some keywords or some threads to follow up on that I think can be really interesting. STEPHANIE: The infinity of the internet. I love that phrase. I don't think I've heard it before, but it's very evocative for me [laughs]. And I like what you said about it helping you give a direction and to kind of surface those keywords. In fact, it almost kind of sounds like what I was mentioning earlier about using Slack for, right? And, in that case, the hive mind that I'm pulling from is my co-workers. But also, I can see how powerful it would be to leverage a tool that is guiding you based on the software community at large. JOËL: Something I'd be curious to maybe lean into a little bit more are some of those slightly more specified questions where it does give you a code snippet, so something like writing a file to disk where, right now, it's, you know, five characters. I just pop up Alfred and type up Ruby F, and it gives you the file docs, and it's, you know, right there. There's usually an example at the top of the file. I copy-paste that and get working. But maybe this would be a situation where some AI-assisted tools would be better. It could be searching through something like ChatGPT. It could be maybe even something like Co-pilot, where, you know, you just start typing a little bit, and it just fills out that skeleton of, like, oh, you want to write a file to disk in Ruby. Here's how it's typically done. STEPHANIE: Yeah, you bring up a good point that, in some ways, even the approaches to searching we were talking about originally is still just building off of algorithms helping us to find what we're looking for, right? Though, I did really want to recommend an awesome talk from Kevin Murphy, from a RailsConf a couple of years ago, that's called Browser History Confessional: Searching My Recent Searches. The main message that I really enjoyed from this talk was the idea of thinking about what you're searching for and why because that will, I think, help add a bit of, like, intentionality into that process. You know, it can be very overwhelming, but let that guide you a little bit. One of the things that he mentions is the idea of revisiting your own assumptions with search. So, even if you think you know how to do something, or you might even know, like, how you might want to do it, just going to search to see if there's any other implementations that you haven't thought of that other people are doing that might inform how you approach a problem, or at least, like, make you feel even more confident about your original approach in the first place. I thought that was really cool. That's not something that I do now, but definitely, something that I want to try is to be, like, I think I know how to do this, but let me see what other people are doing because that might spark something new. JOËL: We'll put a link in the show notes to this talk. But I was lucky enough to see it in person. And also would like to second that recommendation. It is worth watching. From this conversation that you and I have had, I'm having, like, two main takeaways. One is kind of what you just said, the idea of being a little bit more cognizant of, what kind of search am I doing? Is this a sort of broad how do I X, where I don't even really know where to start? Is this, like, something really specific where you just don't know what kind of syntax you want to use? Is it an error message where you just want to see what other people have done when they've encountered this? Or any other, like, more specific subcategories. And how being aware of that can help you search more effectively. And secondly, don't limit yourself to the public internet. There's a lot of great information in your company's Slack or other instant messaging service, maybe some kind of documentation system internal, some kind of wiki. And those can be a great place to search as well. STEPHANIE: If we missed any other cool searching tips or tricks or ways that we might be able to improve our processes for searching as developers, I would really love to hear about them. So, if any listeners out there want to write in with their thoughts, that would be super awesome. On that note, shall we wrap up? JOËL: Let's wrap up. STEPHANIE: Show notes for this episode can be found at bikeshed.fm. JOËL: This show has been produced and edited by Mandy Moore. STEPHANIE: If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter. STEPHANIE: Or reach both of us at hosts@bikeshed.fm via email. JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week. ALL: Byeeeeee!!!!!! ANNOUNCER: This podcast is brought to you by thoughtbot, your expert strategy, design, development, and product management partner. We bring digital products from idea to success and teach you how because we care. Learn more at thoughtbot.com.

Stephanie experienced bike camping. Joël describes his experience during a week when he's in between projects. Stephanie and Joël discuss the concept of code ownership, the mechanisms to enforce it, and the balance between bureaucracy and collaboration. They highlight the challenges and benefits of these systems in large codebases and emphasize that scaling a team is as much a social challenge as it is a technical one. Out Our Front Door (https://www.oofd.org/) Conway’s Law (https://en.wikipedia.org/wiki/Conway%27s_law) Transcript: JOËL: Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Joël Quenneville. STEPHANIE: And I'm Stephanie Minn. And together, we're here to share a bit of what we've learned along the way. JOËL: So, Stephanie, what's new in your world? STEPHANIE: This weekend, I went bike camping for the first time. So, it was my turn to try out the padded bike shorts and go out on a long ride, combining two things that I really enjoy: biking and camping. It was so awesome. We did about 30 miles outside of the city of Chicago to close to the Indiana border. And we were at a campground that's owned by the forest preserves where I'm at. It was so much fun. I packed all my stuff, including my tent and sleeping bags. And it was something that I never really imagined myself doing, but I'm really glad I did because I think it'll be something that I want to kind of do more of in the future, maybe even do multi-day bike camping trips. JOËL: So, what's your verdict on the bike shorts? STEPHANIE: Definitely a big help. Instead of feeling a little bit sore an hour or so along the bike ride, it kind of helped me stay comfortable quite a bit longer, which was really nice. JOËL: Would you do this kind of trip again? STEPHANIE: I think I would do it again. I think the next step for me is maybe to go even farther, maybe do multiple stops. Yeah, I was talking to my partner about it who came along with me, and he was saying, like, "Yeah, now that you've done that many miles in one day and, you know, camped overnight, you can really go anywhere. [laughs] You can go as far as you want." And I thought that was pretty cool because, yeah, he's kind of right, where I can just pack up and go and, you know, who knows where I'll end up? Not that I would actually do that because of my need to plan. [laughs] I'm not that go-with-the-flow. But there was definitely something really special about being able to get from A to B with just, like, my physical body and not relying on any other kind of transportation. JOËL: Yeah, there's a certain freedom to that spontaneity that's really nice. STEPHANIE: Yeah. And I actually went with a group called Out Our Front Door. And if anyone is in Chicago and is interested in doing this kind of thing, they do group bike camping adventures, and they make it really accessible. So, it's a very easy pace. You are with a group, so it's just really fun. They make it really safe. And I had a really great time. There was about 60 of us actually at camp, and they had rented out the entire campground, so it was just our group. And they even had a live reggae band come out and play music for us while we had dinner. And that was a really nice way for me to do it as a first-timer because there was stuff already planned for me, like meals. And I didn't have to worry about that because I was already, you know, just worrying about making sure I got there with all of my stuff. So, if that sounds interesting to you and you're in Chicagoland, definitely check them out. JOËL: That's a great way to bring in newer people to say, let's have a semi-organized thing, where all you have to focus on is the skill itself, you know, can I bike the 30 miles? Rather than planning all the logistics around it. STEPHANIE: Yeah, exactly. Joël, what's new in your world? JOËL: So, speaking of planning and logistics, this week, I'm in between projects at thoughtbot. And on the Boost team that I'm on, we've introduced a kind of special rotation for people who are in between projects where we have an internal project, where just internal strategic initiatives that we want to push forward. Whoever is unbooked gets to work on that. So, it's a small team with a very high churn. And one of the things that we do is every week; we have somebody act as the project manager for that team. And I was in between projects this week. I was assigned that project manager job. And so, I've been doing that in addition to some of the tickets myself, and that's been really interesting. STEPHANIE: Cool. I really like how that role is rotated among team members. JOËL: Yes. And the whole team itself is very high churn. So, somebody might be on that for just one week and then rotate off, and a new person comes in; maybe someone's on there a couple of weeks while we're waiting to find them a project. But we're always looking to prioritize booking people onto new client projects. And so, whoever is on that team, typically, is there for a short period of time. And so that means that the project manager role has to rotate a lot. But also, just in general, as you're managing tickets, you have to deal with the fact that people are not going to be on this project long-term. This is just, they're here for a few days, and they get some things done, and then they're moving off. And I think that presents some unique challenges in terms of the project management side of things. STEPHANIE: Yeah. What kind of challenges did you find interesting in this role for the week that you were on it? JOËL: So, in particular, I think making sure that outstanding work from the previous week gets done, especially when the people who were working on that ticket are no longer working on it. So, they may have done some partial work and then moved on to something else. And then, you have to ascertain the state of the ticket. Has it been completed? If it's only partial, what parts have and haven't? Can this be passed on to somebody else? Is there some unique knowledge that the previous person had? Has the code been pushed up? That kind of thing. STEPHANIE: So, that reminds me of something I heard about the idea of being expendable. You know, there are certain industries where anyone else with that skill set can kind of step in and take over for another worker without a lot of issues, and they can continue on doing that work. So, I'm thinking about, you know, maybe doctors or pharmacists where they have that, like, shared skill set, and everything is documented enough so that they can just take whatever their case is. And if someone is out, it's not a big deal because people can just step in. And I'm curious about if this is something that could work for software development. JOËL: I think it is important to have a team where nobody is irreplaceable. When it comes down to individual tickets, one of the things that I've been pushing for is that, at the end of the week, I would like to not see any tickets remain in the in-progress column. We're using a Kanban-style board. So, ideally, all work either moves to the done column or moves to the to-be-done column for next week. And it's no longer owned by anyone, so people have removed their faces from it. Ideally, though, if you pick up a ticket during the week, you get it to completion. So, one thing that I've been really pushing with our team this week is splitting tickets up. If this feels like it's bigger than a few days, then it needs to be split up, and part of it gets done moves to the done column. Part of it might be some work that somebody else is going to pick up next week; move that to the to-do column. And so, that way, at the end of the week, we have, ideally, a column full of things that were pushed over the finish line that are done. And then, we have a column of things to be done next week that nobody has kind of called dibs on yet. So that then next week, when we have a new group of people coming in, you don't just look at this column of to-do things. It's like, well, all of these have someone's face on them. I'm not able to pick up anything, so now what do I do? By having those all kind of fresh and available to be picked up, you make it easy for the next batch of people to hit the ground running on Monday morning. STEPHANIE: That's really interesting. You said you were doing this Kanban style, but it almost kind of sounds like one-week sprints in a way. JOËL: Kind of, because the way we book people onto clients is typically on a per-week basis. And so, if there's going to be a gap between clients, typically, it's in increments of a week. Because they're on the project for a week, it doesn't necessarily mean that we're tracking the tickets on a per-week thing. So, it's not like, oh, we're committing to doing all of these tickets by the end of a particular time or anything like that. We are working in a more Kanban style where there's a backlog, and you pull tickets, and whatever gets done gets done. What we do try to do, though, is not have individual tickets hang in the in-progress column over a week boundary. So, there's a nuance there. I guess there's some ways in which maybe it feels a little bit sprint-like. But I think we are running in much more of a Kanban-style workflow. STEPHANIE: Yeah, that makes sense. JOËL: It's really to deal with that churn and the idea that even though the ticket might stick around for a while or maybe it gets split up into multiple small tickets, the people are switching constantly. And so, making the workflow play nicely with the fact that the team is churning on a weekly basis kind of adds an extra, you know, a little bit of spice to the project management side of things. STEPHANIE: Did you find yourself being the one to break down tickets to make sure that they weren't larger than a week's worth of work? Or did you work with the developer themselves to find opportunities to break out what they were working on if we got to the mid-week and progress wasn't looking like it would be completed by the end? JOËL: I've left this up to individual developers. This is more of a broad conversation I had with our team, kind of saying, "Hey, here's our goal. We want to get some things done by the end of the week. If we don't think we can get them done, here are some strategies I recommend. I'm available to pair if people want it." But I didn't go through and estimate all the tickets and split them up. I did a little bit of, like, grooming ahead of time. So, I had a sense of when we started the week if tickets felt roughly sized correctly. But oftentimes, you know, that kind of thing, you start working on it, and then you realize, wait a minute, this is a bigger ticket than I thought. STEPHANIE: Yeah. I think even just having someone check in and be like, "Hey, how is progress? Can I support you in making sure that you're able to get to somewhere that feels completed by the end of the week so that the rest of the work is set up for someone new to take on?" That seems really valuable to me. Because as an individual, I'm like, yeah, I don't know, I'm maybe heads down just deep and trying to get my thing done, but maybe not so aware of progress and relative to how much time I've spent on it. And having just someone prompt me on that could help kind of pull myself out a little bit, you know, come out for some air and be like, oh, actually, you know, this is a good spot for me to break this down. Do you have any insights into this week that you might be bringing with you into client work or anything like that? JOËL: And I think this has just given me an even deeper appreciation for breaking tickets down. Because of that arbitrary end-of-the-week deadline, I think that forces more tickets to break down in a way that I might say, oh, well, I picked up a ticket on Thursday for a client. It can totally bleed into next week; that's fine. It's still a fairly short ticket, just, you know, I started the work later. And so, trying to make sure that tickets get scoped down really tightly, I think, is an area where I could probably benefit from that discipline on client projects as well. You know, even if I'm not doing it to the extreme, I'm doing it this week. STEPHANIE: Yeah. I would be really curious to find out if next week the folks who are on this project feel like they're in a good spot to, you know, keep on making forward momentum because they can just pull from the backlog and not have to go and do that knowledge transfer. JOËL: Right. I will see with all of this, right? Maybe even with all the conversations and things, maybe we'll end the week, and I'll have 10 cards in the in-progress column. And it'll be like, okay, we tried a thing this week, mixed success. How do we want to iterate on that idea next week? Potentially with a different team. STEPHANIE: Right, exactly. JOËL: I feel like one way to maybe summarize the type of work that I was doing this week is that it's a kind of a scaling challenge. But over time, the team itself is small, but it's constantly churning. And I think you've been working on a team where it's kind of had a similar problem but in a different dimension. You're scaling over team size, actually a massively large team, and seeing some of the challenges there. What are some of the things that you've been facing? STEPHANIE: Yeah. So, my current client project, I'm working on a codebase where there are hundreds of developers also working and committing to this codebase daily. And this codebase is really massive. There is so much stuff going on. And I've really only explored the world of the particular team that I'm on. But I recently had to do a little bit of work in some code that is owned by a different team. And I actually really appreciated the way that we were able to collaborate across, I guess, ownership boundaries. And I was really interested in talking about some of the different ways that we've seen the idea of, like, who is owning, and, like, who is accountable for areas of the codebase once you reach a certain size. So, what was really convenient about the way that I was working was that in my pull request, there was an automated step that told me I needed specific owner approval on the code that I was writing because I was touching some files that were owned by a different team. And it gave me all of the handles for the people on that team. So, I knew who to go talk to. And it ended up being that that team had a public Slack channel specifically for people outside to ask them questions about their domain. And they had a rotating ambassador system. And so, in the Slack channel, in the channel topic, it said who was the ambassador for that week. So, you know, I saw who it was. I got to @ them and say, like, "Hey, like, I'm working on some of these files for this feature for my team. And, like, here's my pull request. Could you give me a review?" JOËL: The more you're describing this, the more this is feeling very large team, almost bureaucratic systems. I'm hearing public Slack channels, which implies that teams have private Slack channels. I'm hearing, like, a rotating ambassador. One word that you mentioned that I'd like to dig into a little bit is the idea of ownership because I think that the concept of ownership is present on probably most teams, but it probably means wildly varying things. And it sounds like on your team, it's a very kind of codified thing. So, what does ownership look like on your project? STEPHANIE: Yeah, I love that you asked that question because you're right; it is codified, literally, in the codebase. There are ownership files that are in the repo itself where they've specified, like, all of the models that a team owns, you know, down to the names of the files themselves, or maybe a namespace. It has the team name and all of the team members' handles. So, that's how it was able to tell me in an automated way, like, hey, reach out to these people. It was really interesting because it was pretty frictionless on my end, where all I had to do was see that, you know, I couldn't submit my pull request until I got that approval. But it was enough friction to be, like, well, you can't just, you know, change files in this domain without someone with extra context taking a look. JOËL: This reminds me a little bit of a system that GitHub has where you have this CODEOWNERS file that you can add to a repo. Have you messed around with that at all, or kind of seen how that looks? STEPHANIE: I have a little bit. I think I've only seen it in the context of being notified that someone is wanting to submit a pull request, but I'm not sure if it does gate merging based on ownership. Do you know if that's the case? JOËL: I don't. I think you can set it up to automatically request reviews from owners. And on a large repo, the owner could be...I assume this is based maybe on directories, or it might be a regex pattern. I forget the exact details. But you can have owners for partial parts of the code instead of owners of the entire repository. So, then, if you make a change to a particular part of the code, it would ping the correct person automatically to review your code, which sounds like a really nice feature. STEPHANIE: Yeah, absolutely. I think for the project that I'm working on, this definitely seemed like a custom process that they, at one point, decided to enforce. I'm not really sure about the history of how this came to be. But I found it actually quite a good way to meet people who are working in other parts of the codebase. The person who happened to be ambassador that I pinged was so helpful in just, you know, making sure that I kind of understood the parts of the code that they owned that were honestly, like, quite complex. Like, I would not have felt confident just going ahead and making those changes necessarily myself because this is a pretty legacy codebase. There are quite a few gotchas, and they were able to point some [laughs] of them out to me. Yeah, having that extra confidence was helpful for the particular feature I was working on. But it did also kind of give me a little pause because I've not worked at such a scale where there was so much uncertainty about the domain and that being so diffused across like I mentioned, hundreds of people. JOËL: Do you think that this ownership system that's in place helps manage the complexity of scaling up to a team of hundreds of developers? Or does it feel like it kind of just adds a lot of process that gets in your way? STEPHANIE: Ooh, that's a good question. It seems like kind of a chicken-and-the-egg situation because I felt better with someone else's input, right? Like, with someone else with more domain knowledge than me about what I was touching to be, like, "Yeah, like, this looks good to me," giving the plus one. Whereas if that didn't exist, maybe I would have tried to seek it out on my own. But I would not have known where to start, right? I would have to ask around and be like, "Hey, like, who has worked in this directory before?" or whatever. Or I could have just went ahead and merged my code and hope my lack of context didn't really cause any huge problems, like outside of what was covered by the tests. But this is helpful for, like, where the codebase is at, you know, and the size it has grown. JOËL: Do you think requiring an owner to review the code puts maybe an undue burden on the person who's the owner and that they might end up spending a lot of time reviewing code because they now kind of manage that part of the app? STEPHANIE: Yeah, that's a really good question. I think it can. But I also feel a little better that that role is rotated, that everyone on the team gets the opportunity to really, like, focus on that. And I'm pretty sure the way it works is that that is their main focus for the sprint, or the week, or whatever, and that they're not assigned any other feature work but to prioritize being that ambassador. So, in some ways, that is a lot of process, right? And there is that trade-off of having to allocate someone specific to answer people's questions. But at least from what I've seen, it does seem like a necessity because people do have questions, right? And I think they have figured out a system where it's very clear who you're supposed to talk to, and that accountability aspect of it has been met. Because I've also, like, worked on teams where that role is not well defined. People don't want to do it. And it's almost kind of a bystander effect where someone asks a question, but no one is specifically responsible for answering it, and so no one answers it. JOËL: Oh yeah. Yes. And then you get kind of the cost of the bureaucracy without the benefits of kind of diffusing that knowledge. So, we've been talking a lot about how this kind of ownership system can be really beneficial despite the overhead for a team that's 200 or 300 developers and where nobody knows all of the code or all of the nuances. And kind of at the other extreme, it's absolutely not worth it for a team of two or three developers where everybody knows the code, and there's kind of shared ownership of the project. Somewhere in between, there is where you start having maybe some of those conversations about scaling the team, and do we need to introduce more process? In your experience, where do you think introducing some sort of ownership system like this starts becoming valuable? Or maybe what are some of the questions that a team should ask themselves to gauge, like, at the size we're at right now, would we get value from an ownership system? STEPHANIE: Yeah, that's a really good point because as you were saying that, I was just starting to think of, yeah, I've certainly worked on projects where I have reviewed every piece of code that is to be merged, right? And then, at some point, that starts to change where, like, I can't do that anymore. And that transition has always been really interesting to me. And then, I think there is, like you mentioned, another one where it's like, okay, now we aren't able to review everything, but, like, how do we trust that the code that is being merged, even if we don't all share that same context, is up to the quality we want it or is bug-free? Because without that context, there's always the opportunity that something might be missed. I think I've seen that on teams, you know, really look like more bugs than usual, right? And maybe there is, like, actually, like, a big problem, and the site is down. And maybe there is, like, a post-mortem or something to discuss, like, why this happened. And, you know, it turns out that the siloing or, like, the lack of context sharing was partly involved. And so, I do think there are definitely symptoms when we're starting to firefight a little more [chuckles] that might be kind of an indicator that the app has grown to a point where some context is being lost, and there are not guardrails in place to do our best to, like, share it, like, when we can and not when it's too late. JOËL: Would it be fair to say that your recommendation is the team should not have an ownership system and kind of stick to everybody reviews all the code as they grow until they start hitting actual pain points, such as real bugs caused and, at that point, let that pain or maybe even the post-mortem be the thing that triggers the introduction of an ownership system? STEPHANIE: I think so. I have not seen something like that proactively introduced. I would be curious if anyone has experienced something like that. But, you know, I think it's okay for change to be a little painful, right? And that's part of the growing pains of becoming a larger team, or organization, or codebase and continuing to reevaluate. Though, I guess I would be a little cautious about, you know, jumping straight to introducing processes or policies, right? Because those can be really hard to undo if they end up not being actually helpful for the root cause of the problem. But, like, how you experimented with making sure that, you know, we didn't have any in-progress tickets for that project. The idea of just trying something and seeing how it works and kind of getting the team's feedback that is really valuable to me, at least as an IC. And, yeah, just making sure, like, you know, hearing from all of your team members on how those processes are changing the way they work and if it's feeling good or not. Like I said, I enjoyed the process on my client project because it helped me feel more confident that the code that I was changing...because I can't possibly gain all of the knowledge that the owners of that area of the code have. It's just not going to happen. But also, I can imagine it being maybe not so good for someone else, right? It kind of being a barrier or being frustrating because, oh no, they really need to merge the code. And maybe they made the smallest change in a file owned by another team, right? And having to jump through that hoop. JOËL: Yeah, that has absolutely never happened to me. STEPHANIE: Really? Because it sounds like it has. [laughter] JOËL: Yes, it absolutely has. We've been kind of throwing around the idea of ownership the idea of team almost interchangeably as if they're one-to-one. And I want to lean a little bit into this idea of the team. Because I think there's an implicit assumption here that, within a team, there's enough knowledge sharing that happens, enough shared context, that everybody can kind of understand all of the code for their team, and that knowledge is just shared around, so you don't need these extra processes within teams. But maybe once you start having multiple teams as part of your engineering department, then there starts to be some friction or some lost context that needs some mechanism to get around. Does that sound about right to you? STEPHANIE: Ooh, I think that depends because even within my team, we are working on different projects, and I am definitely not on top of, you know, what some other folks are working on. And even within our team, there are silos. The difference there, though, is that I know who they are. Like I still am in contact with them in our daily syncs, that the barrier to finding someone who has the right information is much lower. So, yeah, I think that is definitely a part of it, too, if, like...I think just the social barrier, even of, like, reaching out to someone you don't know and being like, "Hey, like, can you review my code?" that is [laughs] kind of...can be a little scary. And the dynamics definitely feel different within a team and between teams. JOËL: Yeah, and definitely just the idea of, like, someone you see every day for your daily sync, you're going to feel much more comfortable reaching out to them for help or for a quick review than to a total stranger. So, it's interesting that you mentioned the social aspects of things. I don't know if you're familiar with Conway's Law, the idea that the technical structures of our code, over time, end up reflecting the social structures of our teams. STEPHANIE: Yeah, that is something that makes a lot of sense on the project that I'm working on now, where the boundaries, like I mentioned, between teams and between different namespaces are semi-rigid, I suppose, right? Rigid enough that, you know, there is a process but not so high that it becomes a burden, at least in my opinion. But for another feature that I worked on, I actually had to interact with an external system that's owned more by the parent company of my current client. And that process was definitely more rigid. And I had to figure out who to email and had to, you know, look up this person's profile in the company directory to make sure that, you know, I was talking to the right person who had information that was relevant to me. And then, you know, even, like, the technical aspect of talking to this external service had a lot of various barriers and, you know, special authorization and configuration that I needed to set up. So, definitely felt that in terms of the different levels of ease and talking to systems owned by different parties. JOËL: So, the fact that there's, like, an actual, like, departmental or even, like, corporate boundary, definitely showed up in, like, a very hard boundary in the code as well. STEPHANIE: Yeah, absolutely. JOËL: And I think taking this to an extreme, I've seen this happen when teams want to introduce microservices. And oftentimes, the boundaries of those microservices are not necessarily driven entirely by technical reasons, but they're often by social reasons. So, we can say, hey, this team is going to own this service, and everybody else only needs to interact with a public API. And we can make all sorts of changes internally, and you never need to know that. They will never break your code. And also, we don't need to bother each other or feel the need to fully deeply understand the internals of each system. STEPHANIE: Yeah. Once you're introducing APIs that are accessible to a certain group of people and having to navigate, you know, making changes to the API or aligning in the expected structure of the, you know, communication that you're sending between them, that is definitely a pretty rigid boundary [laughs] and ends up being a lot of overhead to talk to those systems. And I certainly have been in the position of trying to communicate with the people who built and designed those systems and figuring out how to get on the same page. And even just recently, I was accidentally sending something as an array, and they were expecting it as a string. And that caused all these problems of making the request happen, you know, successfully. And we didn't even realize it until someone pulled out the doc that had the API schema and pointed out that there was some miscommunication along the way. JOËL: And that can be such a hard boundary around even, like, the idea of ownership. So, you were talking about how, earlier, when you were working in code that's maybe owned by another team, they might want to review it before it gets merged. So, there's a bit of a gatekeeping there. When a team transitions fully to microservices, I've seen it go almost, like, more extreme where it's even, like, you don't even change the code. You submit a ticket into our system. We will prioritize it, and then eventually, we will build your feature. But you don't even get to make a change to the code and have us approve it. We're going to make all that because we own it. So, it kind of feels like taking that ownership idea and then just really running to a full extreme. STEPHANIE: Yeah, right. That makes a lot of sense in the lens of Conway's Law if those are the processes they have in place for navigating cross-team collaboration or communication. Because, at some point, maybe they just reached a level where it had to be enforced that way because maybe things were getting dropped, or more casual lower barrier connection was too overwhelming or just not working for the organization. JOËL: I think what I've been hearing just now and then just more broadly throughout the episode is that while there's a lot of interesting technical solutions that can make things better, at its root, scaling a team is a social problem. And it's all about how your teams communicate with each other so that you can scale smoothly and that the system doesn't suffer from adding more people. STEPHANIE: Yeah. I think this is an area where I would love to hear any thoughts from our listeners about how their organizations handle something similar because I find all of this really interesting. And, you know, it ends up impacting my day-to-day work in a very real way. And so, if other places have figured out how that scaling and, you know, social and technical boundaries work in a way that feels good, I would love to know. JOËL: On that note, shall we wrap up? STEPHANIE: Let's wrap up. Show notes for this episode can be found at bikeshed.fm. JOËL: This show has been produced and edited by Mandy Moore. STEPHANIE: If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter. STEPHANIE: Or reach both of us at hosts@bikeshed.fm via email. JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week. ALL: Byeeeeeeee!!! ANNOUNCER: This podcast is brought to you by thoughtbot, your expert strategy, design, development, and product management partner. We bring digital products from idea to success and teach you how because we care. Learn more at thoughtbot.com.