Rails Business
Brendan Buckingham and Ryan Frisch talk about developing with Ruby on Rails and how to leverage it to build a business.
Rails Business
Discussing Documentation
Use Left/Right to seek, Home/End to jump to start or end. Hold shift to jump forward or backward.
In this episode, Ryan and Brendan discuss the importance of documentation within a business and development context. They cover various types of documentation, including internal, user-facing, and code comments, and highlight the necessity of clear communication from story writing to feature documentation. They also share insights on tools and methods for keeping documentation organized and accessible within their teams.
00:00 Introduction and Greetings
00:26 Diving into Documentation
02:48 Defining Documentation
05:12 User Stories and Documentation
08:12 Internal vs External Documentation
15:54 Organizing Documentation
21:09 Centralizing Resources with Trello
23:02 Balancing Multiple Documentation Tools
23:40 Challenges with Search Functionality
24:41 Effective Use of Trello Tags and Labels
27:54 The Importance of Code Comments and Commit Messages
29:28 Rebase vs. Merge: A Developer's Dilemma
30:16 Interactive Rebase: Cleaning Up Commit History
36:02 Concluding Thoughts on Rebase and Merge
Welcome to the Rails Business Podcast. I'm Brendan Buckingham. And I'm Ryan Frisch.
Ryan:Hey man, how's it going?
Brendan:good. Yourself? I.
Ryan:Not too bad. What are we, uh, what do we wanna talk about today?
Brendan:Documentation has been a big thing on my mind. I thought maybe we could dive into that a little bit. See where it takes us
Ryan:Okay. What about documentation is on your mind?
Brendan:a lot, really. And it's not just documentation. It kind of starts all the way
Ryan:I.
Brendan:the story writing, but it ends up with, how well is the story written to begin with, to essentially give good documentation at the end and all the things that that. I guess has in the middle of it, right? It's first off, you get a good story. Obviously you could hand it to a developer, they could hopefully run with it, not have too many questions. And then once the story's done, then hopefully the person it can look at it, understand it well enough that they don't have to, again, ask too many questions of the developer to say, what did you build here? And then once that's built and maybe shipped, then it could go to, say your marketing department or. Other people in the company or even users, and they can understand kinda either the documentation of it or just what was built there. So there's really a lot to unpack there.
Ryan:Yeah, so.
Brendan:of it's kind of on my mind. So what do you, what, what tickles your fancy
Ryan:Yeah, I mean, I think the first question I'd ask is, you know, what is the, you know, we're the Rails Business Podcast, right? So what is the business objective? What are you trying, is there a problem you're trying to solve here that is, you know, maybe the subtext that you, you haven't said out loud.
Brendan:Great question. Yeah. I think the problem that I'm trying to solve here is communication at the core of it. It, and I can give some examples too, like of. Where the communication and the lack of this documentation has been a problem, you'll get a story to the user or, or the developer, and they'll be working on it. you get to the point where they've worked on it maybe for a couple days, and they come back to you with a review. And either I get more information from somebody on a different team that's asking for this, or I'm testing it myself and I realize the workflow sucks or it's just not gonna be great. so it, it leads to rework in this case at least. to me that also goes back to communication at the beginning of what we wanted to build wasn't good, so therefore the user story wasn't adequate. And then luckily in this case, we caught it so the documentation was better. But that doesn't always happen either.
Ryan:All right, so hold on. I, I'm, I may be thinking of documentation as something different than what you're referring to as documentation. So what's your definit, do you have a definition of what documentation is? I.
Brendan:So I mean, the documentation I'm thinking about right now is mostly internal. Like, how do you use the thing that was just built, but it also could be user facing, right? Maybe it's a knowledge base that you're gonna share with your users so they know how to use your product. Or maybe it's a press release or a, uh, you know, any kind of change, log release kinds of things that you could. Include for customers. So there's a lot of different, it could all be the same, but like now I'm thinking internal mostly.
Ryan:Okay. Well, it, it strikes me as we're, we're I think talking about maybe two separate thought processes, right? Like one is, how to use the feature. And that could be, whether it's internal, external, it's useful to somebody outside of development to understand how a feature works, which I think is different than, you know, perhaps documentation on a ticket and how you communicate the idea for the feature. To the developer and get you know, make sure that the work being done is in line with the vision of the internal stakeholders, right? Whether that's you as their reviewer or you know, the marketing department or the product manager if you have one. Right? And, and I think those are, are two related, but pretty separate things. And I would argue that the. Documentation for the developer. This is really about the internal process, right? Like how do you ensure that they're on the right path early and often, and how do you get your internal stakeholders all on the same page before the work starts? Um. So that might be the sort of like documentation leading into development, if you want to think of it that way, versus documentation coming out of development, which then is the, the other part of documentation I was talking about. So with that definition, do you have any additional thoughts? Am I thinking about this differently than you, or are we on the same page?
Brendan:I mean, I think we're in the same.
Ryan:Atmosphere.
Brendan:page, but we're definitely close.
Ryan:Okay.
Brendan:Yeah.
Ryan:Well, so what, what didn't what from what I just said, what, uh, what do you disagree with or what do you have questions on, or, what do you think of it differently?
Brendan:I think the where I'm maybe still a little I guess trying to differentiate between what I was thinking about and what you're saying is I still, I'm still making the connection of where the documentation or the, just the user story starts and all that communication and how it turns into the documentation later. Now you already admitted there's a connection there, but that they are different enough and I would agree with that, that is certainly a difference with the way a user story is written versus the way the documentation is written. I think what I'm focused on mostly, and maybe that's not quite right, is that the better the user story is written, the easier it is to turn it into documentation, I guess is maybe where. What I've been thinking about a lot more, this really just comes from, you know, continually running into user stories that are not well written or, and, and the rework thing is, is definitely a separate thing, right? Because like, that only comes down to the user story. That really doesn't have anything to do with documentation, whether it's internal or external. but, so maybe a, a different way to frame this, or maybe a better way would be how. Do you handle keeping up with all this stuff, right? It's like, how do you get a good user story to begin with that it lends to better documentation the end of it all.
Ryan:I guess my first question, and I think you're sort of implying this, are, you know, do, do they, does it need to flow from one to the other? Does it, does a user story need to flow into documentation? Like, or is it just that you, I. You know, is there an perceived value that if we wrote user stories in a different way, that, you know, it would take less effort to turn it into documentation? And it is it actually worth it? Right? Like so for example. When, when I read a user story internally, you know, whether it's a good or bad user story is a, a completely separate conversation. But the person who writes the documentation for our end users is not me, right? It, it never is. And, and it's like, it's a completely different language. You, we, we put it together in a completely different way than a user story. Other than, you know, the person who's doing that writing, having to understand how the feature works. The two aren't related for us.
Brendan:Well, I think what you said there might be the key though, is that as long as the user
Ryan:I.
Brendan:is written well enough that the person gonna, that's gonna write the documentation can understand it. that's maybe what I'm trying to get at more than anything. Like maybe. Focusing on just documentation isn't quite the thing that's the big deal. It's just c to take a step back. So to like, to give a better example of why I think this is important. Let's just say that we're building a internal facing some, some sort of tool that we want to use internally. And I know we'll just make something up. We're like adding new customers. We wanna put them into different buckets or something. So we want some, maybe some buttons on the page that do different things depending on which one you click. And let's take it from. Bad user story that basically just like has, not enough information, maybe there's a bunch of questions asked, but at the end of the day, the developer asks those questions either in Slack or wherever, but not in the story. And so by the end of the feature being built, ends up with the marketing team or whoever's gonna write that documentation you were just talking about. Not having a good user story or at least a good place to go for all of the information they need. so it's either we write something new so that they know what the feature was built to do. And I mean, that could be a lot of different things, like a pull request should have that, but most marketing people at least don't have access to those. And so the, yeah, I guess that's. I that's a good example of what I see at least is that sort of thing happening where the user story, by not being adequate enough and also making me think that it's not like the. Marketing team or, or whoever, not on the dev team is not even necessarily going to see the user story, but having a user story or even maybe a good pull request with good acceptance steps. Somewhere you could pull, what is this feature? And hand that off, I guess is, is maybe the, the thing that really matters to, in my mind.
Ryan:Okay I got some thoughts in no particular order, right? One is, Is there. Does your thought process change whether this is like a simple feature versus like a more complex feature that might have some functionality like hidden in the domain, in the code? Like the domain logic that isn't necessarily obvious in the view, right? Is that like, are you running into that situation or.
Brendan:That's a good question and the answer would be yes. It does depend. There's certainly internal things or even, you know, maybe simple user things that are so simple that doesn't need the documentation. I would agree with that a hundred percent. But also bring up a good point that there are certainly times when things are built, especially internally, that do kind of re require some domain knowledge or something that is. Maybe more obscure, partially because it's internal and so it's not designed well or whatever,
Ryan:Oh, so,
Brendan:like it needs some documentation to handhold someone to actually do it, right?
Ryan:so I, I think there's a couple ways I've handled that in the past on my end, which was one is. If it's an internal tool, often I'll just put the documentation right on the page, right at the bottom of the page and just say, all right, well, you know, I don't, I don't really care how this looks, but the information needs to be there, so I'm just gonna build it into the code, uh, on the page. And now it's there. The assumptions are there, and you can't, or you know that that's one way to do it.
Brendan:Yep.
Ryan:There's the other piece of me that sort of says, all right, well. If you're feeling the need to do this a lot, you know, not the one off like kind of crazy feature, but on a regular basis, then I'd argue we probably need to invest more time in the, you know, the UI or you know, making it so that I. The feature, even if it's internal, is more easily understood without having to dive through, documentation or help docs or whatever. You know, that's obviously easier to invest when it's user facing, but it is probably equally important on the internal side because things that are inefficient that require, you know, to go back and reread and re-understand, you know, that's time wasted for your internal team that they could be doing something more valuable for the customer. And the last thought I had that I can remember at least at this point was that I, I think sometimes it's okay to have to rewrite the documentation for the handoff. It forces the person who wrote the code. To be empathetic to the people that are using the code and to learn how to communicate what a feature does to someone who's a non-developer. And I think that's a good skill to cultivate. Now that goes back to culture. We've talked about culture, like maybe you have a culture that you know, your developers are never gonna do that or don't want to do it or resist doing it or whatever. But I think it is a good practice in general. Um, I. And I thought of one other thing while I was talking, which is when you if a feature is complex enough, to warrant some sort of documentation along with the handoff to the other stakeholders, then maybe there's a training session that's needed and that's recorded and then passed along. That's another way to do it, where you don't necessarily have to write this crazy documentation, but you're gonna do a walkthrough. And as you're doing that walkthrough, you can sort of talk about some of the assumptions that were made so people understand the decision of like why it, it does what it does,'cause we, at Lo Bowl, we uh, we write what I'll call opinionated software. We have a way that we want to do things and we try to write code that allows the user to do it in that way, that that means that our tools aren't for everybody.
Brendan:Yeah.
Ryan:that also means there's a lot of assumptions that we make and sort of very similar to rails, right? Like, you know, convention over a configuration. It's sort of the same idea. You know, and sometimes because of that, the feature works in a way that isn't. You know, maybe as intuitive as like a, you know, something that niches down and has like all the options, right? It's like, all right, now we're, we're gonna do it this way and this is why we do it this way. And that nuance needs to be communicated because, you know, customer success is gonna get that question at some point, and they need to be able to answer. It's like, oh yeah, we've heard that before, but you know, we made a conscious choice to do it this way because of X, Y, Z. And we found that, you know, when you. Arm people with that information that the customer often, you know, they're just used to doing something a certain way. Right. And once you explain why you did, you're doing it differently, they're like, oh yeah, that totally makes sense. This is gonna save me, you know, 15 minutes or an hour or two hours of of time. So you know that there's all that nuance you know, that I see. And it's like, all right, every situation's a little bit different, but. Here's my hot take for the day. I don't often reach for documentation as the first thing,
Brendan:Yep.
Ryan:right? Like a video, a training, a, a walkthrough, uh, you know, some screenshots. Those all probably come before I consider documentation because documentation gets outta date quickly, and I don't want the burden of trying to keep it up. I'd rather focus that time on the tool and making it better. Then, you know, having to write or rewrite or whatever.
Brendan:You bring, definitely bring up a good point that documentation gets stale. That's just the fact and, but I would argue though that a lot of the things that you just named off, you know, whether it's screenshots or videos, like those two for sure are documentation in a different form and It's, and they could also get stale, which is something we've run into. I mean, we've shared like loom videos. With the team, you know, just to say this is what it does. And this gets into a whole nother thing with documentation. Whether you do it or not though, is just like the organization of it. Because even, even if you create it, then, like, where does it live so that people can find it when they need it. and honestly, I, I'm not super interested in diving into that. Solution.'cause I don't have a good answer to it anyways. I will mention though that I, I have started reading the, the para book, the para method that we talked about
Ryan:Sure.
Brendan:And for myself, I'm finding that that is helping a lot. And I am starting to think about like, okay, how could I apply this to the business maybe so that we could organize things better. But,
Ryan:Yeah.
Brendan:may maybe.
Ryan:transformational. We, we, I don't, we'll have to put the, uh, episode in the show notes that where we talked about that so we don't rehash the en the entire conversation, but I. Yeah.
Brendan:And I
Ryan:method's big.
Brendan:though that like the more I get into it, I feel like maybe we wanna revisit it.'cause I think I might have more to add obviously. Say that for another time.
Ryan:Yeah. Happy, happy to dive into that. I did want to go back to something you just said, which was that, you know, your, your argument is that, you know, a video walkthrough is another form of documentation, which I agree with, but that the nuance that I want to communicate is. The video is there. It's not, it's not like the how to, it's not, it's not like, Hey, go click on this button and then fill out the form and, and you know, take this step and then go and do this thing. Right? It's not procedural. It is mostly about the nuance and the, the nuance of. Why something is built the way it is. Right? How the decisions were made to do it that way, right? It's about the understanding of that and that that's true in code when you're talking to a developer, right? Like I, I'm in the camp of, adding comments like that say, Hey, this method does X, Y, ZI. Is a completely useless exercise, right? Just write the method. That's easy to understand and you know, any competent developer is gonna be able to, to look at it as long as it's not like completely abstracted and crazy with bad naming and you know, all this stuff, but comments in the code are great when it's like, Hey, I thought about doing it this way. We started down that path. It didn't work because of this, so now we're doing it this way because, you know, this solves this problem for us. Right? Those you know. Those types of comments are great, and I, I would argue it's the same thing with, you know, documentation when you're trying to, share how a feature works with a non-developer. It's not. Tasks, right? The system should be designed at least well enough where you don't need to be like, go here and click on this button, right? But it is still very important to be like, here's the context behind it. That, that was the distinction I was trying to make. So yes, it is a, a formative of documentation. But the style is drastically different in terms of what I'm talking about, or, or,
Brendan:Yeah.
Ryan:maybe you were saying that all along and we never really got into that, but.
Brendan:that's a good distinction for sure, because when I was thinking of videos for documentation, like we, we do both, like we will share what you just described as like, Hey, this is what the feature I built for the reviewer. But we don't generally share that with, anybody else because a lot of times. Too deep into the code or whatever. We don't really, you know, you, we don't wanna share that. we will do a different video, which is more procedural, which I think is a, a difference that you were just pointing out. And yeah, I mean, that, that I would agree a lot with a lot of what you said there.
Ryan:Between internal and external, right?
Brendan:yeah.
Ryan:The external is gonna be a little bit more procedural and probably lives in a help center. You know, maybe it has a video, maybe it has text. Probably both in internal is, you said you, you weren't sure you wanted to dive into like how to organize it, but I'm gonna dive in just a little bit, right?'Cause it's something,
Brendan:say.
Ryan:yeah, it's something we've been working on. Internally here, which is like, all right, where do we put stuff? Um, and we've tried, but we had an internal wiki for a long time, but that was too hard to update. Our current situation is like, all right, if there is. Like we have a, I have a Wiki on our GitHub for our app. But it's not like I try to document everything. I only document the things that are a little bit more complex. Right? Back to our original, one of your, your original statements. So like, you know, we have an integration with Google Business Profile, right? That's a little bit more complex. Like it's hard to test, it's hard to set up. It's, there's, there's a lot of, you know, external dependencies. So I have a Wiki page on that, right? And anytime I feel the, it's like, Hey, this was a pain for me. Once I try to document it, so that usually it's me that needs to go back and look at it, it's like, all right, I know where it is. So like, there's that developer resource there. And then we have a tr we, we've ultimately ended up on Trello, for. Marketing, sales, customer success resources. Uh, so anytime we do like a, a marketing video, you know, we make sure to create a card and a specific column and you know, we, we make sure that there's a good title and a good description so that the board is easily searchable and, and now at least there's. What we stopped caring about is where the video is stored, right? I don't care if it's on Dropbox, on Google Drive, on YouTube, on Vimeo, uh, by the way, we use all of those, um, which is slightly aggravating, but for a different reason. But now I know that the Trello board has a reference to it, and it's, I have one central place that has everything that's searchable, and that's true for. You know, the only thing we don't really put on there is like the help articles for end users. Those live in their own help center. You know, that's publicly available. So like, you know, I just link, we, we have a, a column which is just like all the link out to anything else that we need. And so far that's working fairly well. I mean, the challenge is still, you gotta remember to go to that board when you're looking for something and that's sort of a behavioral thing that's hard to. Snap out of. But the other purpose it serves is when we hire somebody, we can be like, here is everything. And in that board also has all our hiring resources, all our job descriptions, all the, the links to our websites and our social media profiles. And you know, now you know when someone is onboarding. We might have a board, I'm getting off on a little bit of a tangent here, but we might say like, here's your onboarding board. This is how you're gonna get up to speed on everything. Like the first task is go explore this other board. Start watching some of the videos, like it's up to you where you wanna start. I'm not gonna say, go watch this video and then this video and this video. Just go there and explore. See what. Know, fancies you. And I think that's a better way for people to start to, you know, get up to speed with your way of thinking than it is to sort of put 'em through an all day training where you just dictate to them all day long because it, it lets them be curious and explore the things that they care about. Now, there might be a few things that they have to look at, and I'm sure there's some forms that everyone needs to fill out, but it, it serves that dual purpose and. Yeah, we're still small enough or I'm not sure if that's scalable, but it works for us right now.
Brendan:Yeah, I've got a bunch of questions, but well, one of my thoughts is we do something similar but not quite. So like we have Notion, but we also have Google Docs. The Google Docs are like everybody but the dev team. And then the dev team has notion. And searchable, I think is the key though in a lot of, you want everything in one place for sure. And I think it's okay to have a little bit of separation that I just described because most of the dev team docs are not things that anyone else needs to look at. But there is sometimes where that stuff needs to come over and that's a whole nother thing. But two my questions for you. How do you find the search? Like how well does that work for you? Because with Google Docs, for instance, like just ran into this the other day myself. was searching for terms that I thought would be in the document and I couldn't find it. And eventually I did find the document I wanted, and honestly, I don't remember what it was about, but the terms that I was searching for were not in. It was the key. And so I'm curious for you what your experiences with that.
Ryan:Well first of all, the search on Google Docs, surprisingly, is horrible, right? They're supposed to be a search company. I, I, I don't understand why it's so bad. And I don't think I'm alone in that either.
Brendan:It's not the first time I've run into it, so I
Ryan:yeah.
Brendan:Yeah.
Ryan:Trello. Is Okay. It depends on what search you use. If you use the global search at the top, I find it pretty useless. But if you use the filtering on a particular board, I find it much more useful. Of course. It's like it all comes down to process, right? Like you have to. We have some rules about how to set up a card, right? You have to take the time to write a good title. You have to take the time to write a good description, and you have to tag it, uh, appropriately, right? So like in Trello, we, you know, if you're the person who created the card, you have to tag yourself as the owner. And then we have some, and I don't even remember what the tags are now. It's like, see, what do I have? And we have a bunch of, uh, labels in Trello land that, you know, you can add. So it's like, you know, if it's, if it's for sales and you tag it with sales, and if it's for marketing, marketing and if there's crossover, which happens a lot like a video could be used for sales and for a customer success, you, you tag both of those. Um, and that allows you to then filter down to get a pretty good idea. The columns are organized by medium, so like, PDFs, videos, images, webinars. So that also helps you narrow the search down.'cause like in most cases, you know, it's like, Hey, I remember, so and so did this webinar for sales or marketing and you know, I know it was a webinar and I think it was this name and that gets you a lot of the way there.
Brendan:Yep.
Ryan:but I mean, there, there's no great. I can't stand notion. I don't know why. Like, I'm, I think I'm one of the minority that think it's like the worst interface in the world,
Brendan:Yeah, we started with it a long time ago, and it's just there, but I can never find anything. And, and I have some structure in there, and no one ever follows the
Ryan:Right,
Brendan:Because it, it doesn't,
Ryan:right.
Brendan:You to basically,
Ryan:And that's what the problem we had when we had, we had like a internal wiki on like a Google sites domain that we tried to do that with. And it was the same thing, right? It's not enforceable. I am, I dislike the notion interface so much that we, and I'm not gonna name names here, but we had a vendor that had like a, their own like SaaS app custom. Interface. And at one point they decided that they weren't gonna maintain their own front end and moved everything into Notion. And I was like, I'm done. Right? Like, I, I'm not gonna use notion for this, right? Like, I don't like it. I, I can't explain that, but, I just, my brain in my, either my brain doesn't work that way or there's something else that my wires are getting crossed on, but I just, I can't function in notion at all.
Brendan:Yeah, I, I struggle, and this doesn't have to become the Notion Bashing podcast, but I will just touch on what I find with Notion that is, I. That I do struggle with as well is that there's too many options. It's a, it's like a blank canvas all the time. And I would prefer, and yes, you could pick certain different types of things to use, but even doing that for me turns into like taking way too long to get to where I want to be. And that's one of the things I don't like about it.
Ryan:And ironically, the, the, if you look at like product-led growth seminars, notion is like constantly the one that they use as a good example of how they use templates and everything. And I'm like, I just did too many templates. Don't get it.
Brendan:Yeah.
Ryan:But yeah, I'm a, I'm an equal opportunity bacher. I've already bashed, uh, Google Drive and a couple others today, so it's all over the place.
Brendan:Yep. There was one other thing that. This is kind of going back to your comments and code, but, thing I'd want to talk about since this is our, our documentation episode is, you know, that's a whole nother form of documentation. Just the comments in the code or, just your get history how many times have you or I dove in to get blamed to find out what the heck was going on. And, I don't, I don't have a whole lot to say about it beyond that. I think it's also important to just note that at least on the development side, having good commit messages is essentially good documentation. And I would argue in some way, you know, Ryan, with what you were saying, leaving comments in the code could be put in to get, although, then you get into the argument of, well then I have to do, get blame. And if, maybe, if, for me that was always easy with Vim because I had like a extension so I could just do get blame and see it right away and it's, it was essentially in line. I don't know how it works in like Cursor or VS code or any of those, but I could see the argument why not to do it that way. But that's one thing I just wanted to touch on as well.
Ryan:I think you're, I think you make a good point there, right? The, even if you are on board with the idea of like, not commenting to say what something does, but commenting to explain a decision. Putting it in the code is fraught with future problems, Right?' cause it can still get outta date, but if you put it in the commit message, then it's sort of contextually with the code at the time of the decision, and that is definitely an improvement. You know, I, I was actually working with somebody the other day as like a and we don't need to go into this, but the sort of the rebase versus merge
Brendan:Mm-hmm. Yep.
Ryan:I'm terrified of Rebase. I'll admit it. I don't it, It,
Brendan:But we can talk about that
Ryan:yeah.
Brendan:separately.
Ryan:May, maybe you can make me un terrified of it.'cause I think it's just the fear of the, you know, unknown or breaking something and I, I don't like force pushing anything, uh, if I can avoid it, but, you know, you, you, I think putting it in the, the Git history for the developer side makes more sense than putting it in the code. I, I agree with you on that. But it has to be with the commit message, not on the pull request.
Brendan:Exactly.
Ryan:and that is a little bit harder to do and, and gi although not impossible clearly, but, uh, I think it's not a common workflow. Sure. Yeah. Let's hear it.
Brendan:Exactly what you just said there is why I like Rebase because what I, I don't like to just rebase willy-nilly like all the time, but what I like to do is I like to, go along and do my commits as I go. Not worry too much about what they say. Although I do need some context for this next step with Rebase, which is when I'm done with a feature or at least gonna submit it for a pull request, that's when I will do an interactive rebate and I will basically clean up my timeline, make sure that all my commits are good, and they line up with what you were just saying, that the documentation is in the commit message right there. And that's my opportunity to do it Rebasing and other. You know, at other points I would agree with you. I'm not quite as keen on it, but the interactive rebase, when it's your own branch is the, the thing that I like about it.
Ryan:Okay, so here, here's, this is the conversation I had yesterday, right? Is like, to me that is the value of Rebase is being able to sort of squash your commit messages into one like Or more polished message.
Brendan:Yes.
Ryan:Um. Even if there's multiple commits and there's, there's multiple messages, like you wanna sort of clean it up. But someone pointed out to me yesterday, I don't know if this is true or not that you can do that without rebasing. You can do that with Merge. So the, the, and I'm still trying to figure this out. I've always done the merge workflow, although I, he, I, you know, I see and hear people talk about Rebasing and make the same arguments you're, you're making, and I'm like, I'm interested in it. I just I'm not there yet. But the value to me is in, in cleaning up the commit message, not necessarily the commit timeline. Now, there may be value in, and to me that's what Rebase does, is it resets your work right on top of master, right? So that it's all sort of organized. I. But I'm not, I'm not yet convinced of the value. That may be a very valuable thing. But that's the sc that's what makes rebate scary to me is that you're changing commit history versus just the commit message. Right. Which is less scary, right? That's just text. You know, so I, I don't know if all those ideas are actually compatible or if what I was told is actually correct. I haven't dove into it any further than that. But if you can do the messaging piece without rebasing. That seems like it would be a better solution to me, but there's tons of people that disagree with that statement, so I'm not really sure where I'm at yet.
Brendan:I don't have an answer to that. I'm trying to think through as you were talking there, like how that would work. Can I ask you a question? When you merge, do you click pull request, squash and merge? And obviously not rebase, but like those are the three options you can do in GitHub. Which, which one do you choose?
Ryan:I usually just hit the merge. If I'm doing it in the GitHub interface, for example, I just do the merge.
Brendan:Create the merge, commit
Ryan:correct.
Brendan:Okay.
Ryan:And, and you know, that that is another place to add that context on that instead of just, you know, merge master, you could say, you know, merge and, you know, here's the context, but you, you lose the association with the, you know, individual commits that way. Um.
Brendan:why I like Rebase because Rebase fixes the individual commits. And that's why I'm not sure I understand that, how you could do that with Merge,
Ryan:I, I, I don't know if it, it's possible. I, I was thinking they, they specifically were saying you can squash with merge, which was like, you know, like, so my commit messages typically are like. Add this little thing, add this little thing, you know, maybe it's a little bit descriptive. And then there's like 15 whips in a row when I'm just sort of saving before I have to walk away to like work with the kids or, you know, whatever. And like, none of them are super useful until I merge at the end. Like, so like my thought process was, maybe I need to start merging squashing before I push to master. Like that's one thing. That really only works if I start doing, you know, smaller commits in general, right? Like I, I wouldn't want like a big bang commit and have like, you know, get rid of all context in the, in the history to squash it down. So yeah, there, there's, there's nuance like everything else, but and frankly, I
Brendan:I'll share
Ryan:just, yeah.
Brendan:So back to re You or interactive rebase. think that's what could solve your problem there. I dunno if you've used that or not. And there's a whole workflow that is back to documentation, very well documented by thought pot that I've been using for years and years that does even more than I do these days, but. walks through all the steps. It really helped me, you know, five, 10 years ago, whatever it was, probably more than that. Just really understand why you would do it this way. And at the end of it all, you can even merge your pull request, by the way, without clicking the button and stuff requires a force push, which I know you already mentioned you don't like,
Ryan:All right, well, well, here, here's the thing, right? Uh, just first of all, let's put that link in the show notes 'cause I wanna read it.
Brendan:yes,
Ryan:I'm sure I've, I'm sure I've read it. It a million times.'cause it sounds familiar, but I, let's try it again.
Brendan:forever. Yep.
Ryan:I feel like rebase works when you don't work off of master better, right? Like when you have like a develop branch and you rebase to develop and then when you're ready to go to master, you always merge, right? Because then it keeps master clean at all times, right? You never have to force push to master, which is like, that's the thing that is like, I don't wanna do this. I don't ever wanna force push to master if I can avoid it. I have less of a concern with force pushing to, you know, a, a developed branch because that's sort of undoable. You always have master to fall back to. And you know, maybe that's the thing that I'm missing. I, I know we used to do that and now we don't. I, I don't know when that stopped or why, probably just my inexperience at, at the time. But you know, maybe that fixes the whole fear of force pushing.'cause I. You're not completely clobbering your, your history.
Brendan:Yeah, I mean, I think we could go for quite a while and I know we're, we're getting close to time here, so we should probably, put a pin in this, GitHub and Rebase conversation, and maybe we can get a guest that has another opinion as well at some point.
Ryan:Yeah, that sounds good.
Brendan:yeah, I de I don't think that the force push is quite as scary it's used properly. Right. Like a lot of things. And I, I don't even know what I don't have a whole lot to back that up with. Besides, I never, get your concern about force pushing to master if you know you're, I can't think of a good example, but if, if you're just kinda like not following a specific, flow workflow with Git, but I think the workflow that, again, we'll link in the show notes, I think if you follow something like that, at least then it, to me anyways, it always took away the concern about force pushing to master because it was, it seemed very controlled.
Ryan:I admit, I think a lot of it is the fear of the unknown, right? Like, it, it seems like a scary process and I've never really used that functionality before. So like, until you get comfortable with it yeah,
Brendan:Right.
Ryan:for sure. I, I guess my fear with the force push, just to, to wrap it up, is more that, all right, you, you do your interactive rebase. There is a chance that you. Accidentally exclude work that was completed and pushed right. To master, like as you're rebasing, like if you pick the wrong, okay.' brendan_1_06-19-2025_131221, cause It.
Brendan:do the interactive rebates, it gives you every single commit for that branch. And then you can decide either whether you wanna squash it or rename it or whatever you wanna do. And then it essentially, keeps everything on that branch. And then when you do the force push, the force push typically is when you're merging all of that into master. That's in my experience anyways.
Ryan:I guess my fear is that if you're. Dealing with any sort of conflicts, I think it, it feels like it's easier to accidentally,
Brendan:rebate will still tell you you've got conflicts. It'll, you'll still run into the
Ryan:So, so you have the same problem, regardless of whether it's a merge or a rebase. Right. If there's a lot of conflicts, it's still a pain.
Brendan:Yep. You
Ryan:I think that's fair. All right. Well
Brendan:Yeah.
Ryan:maybe you'll, you'll teach me rebase one of these days.'cause everyone talks about it in a very, uh, positive way. So maybe I'm just behind the curve on this one.
Brendan:Yep. I mean, I wouldn't necessarily say that there's, most people on my team don't use it, so I don't know how widespread it is, but something I like, and I know a lot of people use it, but I honestly haven't seen it with, at least with teams I've worked on as much. So
Ryan:It is definitely a polarizing topic. I, I feel like people are either rebased or merged and there's not a lot of in between.
Brendan:right,
Ryan:Yeah.
Brendan:Yeah, I think that's probably a good place to stop. Thank you for listening to the Rails Business Podcast. You can find all our episodes@railsbusiness.com.
People on this episode
Podcasts we love
Check out these other fine podcasts recommended by us, not an algorithm.
Code with Jason
Jason Swett
Standing in the Fire
Very Good Software
Remote Ruby
Chris Oliver, Andrew Mason, David Hill
IndieRails
Jess Brown & Jeremy Smith
Startups For the Rest of Us
Rob Walling
Vibing with AI Code
Brendan Buckingham