483: Comparing notes on note-taking
Summary
Sally and Joel kick off the episode by sharing personal updates. Joel talks about a D&D campaign where playing an illusionist character forces creative problem-solving, leading to a discussion about how constraints can improve creativity in various domains, from baking to knitting and software development.
They transition to discussing the challenges of parsing CSV files with encoding issues, which prompts a broader conversation about how they capture and retain knowledge from their work. Sally admits to being an aspirational note-taker, relying on sticky notes and command history, while Joel describes his more structured system: a personal wiki in Obsidian where he distills software ideas into small, interlinked notes with thesis statements and supporting text.
The conversation explores different facets of documentation, including using commit messages as a form of journaling, the value of readable Git history for understanding code decisions, and how to handle team communication and clarification on tickets. Joel shares how his note-taking system has helped him generate content for blog posts, conference talks, and even a book he’s writing on web development fundamentals.
They conclude by reflecting on the motivations behind note-taking—aiding memory, enabling reflection, and building a repository for professional growth—and Joel points listeners to articles he’s written about self-aware learning and the mechanics of his note-taking system.
Recommendations
Articles
- Joel’s article on self-aware learning — An article Joel wrote about examining your daily work to extract learning and foster continual growth, which motivates his note-taking practice.
- Joel’s article on his note-taking system — A detailed article where Joel explains the mechanics of his personal wiki, how he breaks down ideas, and structures his interlinked notes.
Tools
- Obsidian — Joel’s primary tool for his digital note-taking system and personal wiki, chosen for its hyperlinking capabilities.
- MonoDraw — A macOS tool Joel has used to create ASCII diagrams, making it easy to embed visual explanations directly into commit messages.
Topic Timeline
- 00:01:10 — D&D campaign and creative constraints — Joel shares that he’s playing a D&D character focused on illusions, which forces him to be creative and think on his feet during gameplay. This leads to a discussion with Sally about how constraints, whether in games, baking, knitting, or software, can often lead to more innovative and interesting outcomes than having unlimited options.
- 00:05:15 — The eternal challenge of parsing CSV files — Sally describes her morning struggle with parsing CSV files, highlighting the unexpected complexities of a seemingly simple format. They discuss the trade-offs of handling every possible encoding quirk versus setting reasonable boundaries for user-submitted files, especially those exported from tools like Excel and Google Sheets.
- 00:09:37 — Personal approaches to note-taking and knowledge capture — Sally asks Joel about his note-taking habits, admitting she aspires to be better at it but mostly relies on sticky notes. Joel describes his system: a digital personal wiki in Obsidian where he stores small, interlinked ideas about software. He emphasizes distilling lessons from solved problems into these notes, but keeps temporary debugging notes separate.
- 00:17:00 — Diagramming and commit messages as documentation — Joel explains that he uses diagramming to organize his thoughts, sometimes keeping screenshots or even creating ASCII diagrams to embed in commit messages using tools like MonoDraw. Sally notes that commit messages are her closest form of journaling. They discuss their commit strategies, including making progress commits and the value of a clean, meaningful Git history for future spelunking.
- 00:24:50 — Team communication and documenting decisions — They talk about where to have clarifying conversations for work (Slack vs. tickets) and the importance of summarizing outcomes back on the ticket for future reference. Joel shares how he documents significant decisions or deviations from convention directly in commit messages to preempt reviewer questions and preserve context.
- 00:28:05 — Motivations and aspirations for better note-taking — Sally explains her motivations: aiding memory for infrequent tasks, enabling more holistic reflection on projects beyond the frustrations of a single day, and feeling like it’s a marker of being a ‘developer who has it together.’ Joel reveals his system helps him build connections between ideas, generate content for blogs and talks, and even contributed to his decision to write a book.
- 00:34:08 — Note-taking as a foundation for writing a book — Joel discusses how his note-taking practice and experience helping others online inspired his book on web development fundamentals. He describes the creative process of writing, where cut content becomes valuable notes for future use, and how mental models he collects often start as notes before being refined for the book or other content.
Episode Info
- Podcast: The Bike Shed
- Author: thoughtbot
- Category: Technology News Tech News
- Published: 2025-11-19T09:00:00Z
- Duration: 00:38:57
References
- URL PocketCasts: https://pocketcasts.com/podcast/the-bike-shed/ce1490c0-4406-0132-c909-5f4c86fd3263/483-comparing-notes-on-note-taking/944f06a8-b6bc-4b33-bba0-af76a01c29f9
- Episode UUID: 944f06a8-b6bc-4b33-bba0-af76a01c29f9
Podcast Info
- Name: The Bike Shed
- Type: episodic
- Site: https://bikeshed.thoughtbot.com
- UUID: ce1490c0-4406-0132-c909-5f4c86fd3263
Transcript
[00:00:00] Autoscaling is a simple concept.
[00:00:04] Automatically add resources when needed, and automatically shut them down to avoid paying for excess capacity.
[00:00:10] How hard could that be?
[00:00:12] If you’ve set up autoscaling yourself, you know it’s not that easy,
[00:00:16] especially using the native autoscalers on platforms like AWS and Heroku.
[00:00:21] That’s why you need JudoScale.
[00:00:23] JudoScale is autoscaling as a service, and they make autoscaling simple and easy, as it should be.
[00:00:29] You can use JudoScale on AWS, Heroku, Render, Fly.io, and more.
[00:00:35] It’s free for low-traffic apps.
[00:00:37] An unlimited plan starts at $25 per month.
[00:00:40] Autoscale on easy mode at judoscale.com.
[00:00:56] Hello, and welcome to another episode of The Bike Shed,
[00:00:58] a weekly podcast from your friends at ThoughtBot about developing great software.
[00:01:02] I’m Sally Hall.
[00:01:04] And I’m Joel Kinville.
[00:01:05] And together we’re here to share a bit of what we’ve learned along the way.
[00:01:08] So Joel, what’s new in your world?
[00:01:10] I’ve been playing a D&D campaign with some of my friends,
[00:01:16] and this coming week is the grand finale.
[00:01:20] So I’m really pumped for that.
[00:01:22] Nice.
[00:01:23] I don’t know a ton about D&D, but I know that there’s like,
[00:01:26] each campaign kind of has a story.
[00:01:28] So where are you playing?
[00:01:30] Yeah, so this is a collaborative storytelling.
[00:01:34] It’s not quite like a video game where you’re trying to maybe play most optimally.
[00:01:40] Instead, you’re often trying to play true to character.
[00:01:44] So it’s a little bit closer to improv with some rules
[00:01:48] than a full-on strategy board game or something like that.
[00:01:52] Yeah.
[00:01:53] This has been really interesting because I’ve been playing a character
[00:01:57] who’s all about illusions,
[00:02:00] which means that unlike a lot of characters where you’re like,
[00:02:03] oh, we’re in a fight and I’m going to attack this person,
[00:02:06] I’m going to cast a fireball, I’m going to do damage,
[00:02:09] I have to just find really creative ways of doing things
[00:02:13] through illusions and misdirections that, if they work,
[00:02:17] is going to have a big impact.
[00:02:20] But it really forces me to be sort of creative and on my toes at the table
[00:02:25] because I can’t just be like,
[00:02:26] I swing my sword.
[00:02:28] I have to find something creative to do, otherwise my impact is nothing.
[00:02:33] Yeah, because you’re good at illusions but not very good at swords.
[00:02:36] Exactly.
[00:02:37] And if I’m having an off night and I’m not creative,
[00:02:39] then a lot of the things I’ll do will sort of fall flat.
[00:02:42] So it’s a character type that really keeps me on my toes
[00:02:49] as far as the creativity and the storytelling
[00:02:51] and trying to find something that will be plausible.
[00:02:55] Yeah, I love how constraints can sometimes improve creativity.
[00:02:59] I watch a lot of competitive baking TV shows,
[00:03:04] which is very niche,
[00:03:05] but often there’ll be one event and then whoever wins gets an advantage,
[00:03:10] which often translates into a constraint for everybody else.
[00:03:13] So the person who wins is the only one who’s allowed to use chocolate,
[00:03:16] and everybody else has to do the challenge without chocolate.
[00:03:20] But I’ve noticed that the advantage rarely actually ends up being that advantage.
[00:03:24] And it seems like those constraints actually help everybody else
[00:03:28] be more creative and produce better things.
[00:03:30] That’s insightful.
[00:03:32] Do you find that you often get better results in your own work
[00:03:36] when you have constraints?
[00:03:38] Well, as a person with ADHD,
[00:03:40] time constraints are the way to get me to do really good work, honestly.
[00:03:43] My brain just, you know, if there’s urgency,
[00:03:46] I’m going to work a lot harder on it.
[00:03:48] But yeah, I think in general,
[00:03:50] constraints can push you to do things you wouldn’t necessarily have thought about
[00:03:54] otherwise.
[00:03:55] Like recently, I’ve been trying to,
[00:03:57] instead of deciding a project that I want to knit and then buying yarn for it,
[00:04:01] I am looking at the yarn I already have and going,
[00:04:04] what can I make out of this?
[00:04:06] In some cases, that gets pretty interesting.
[00:04:08] In other cases, it’s just a lot of hats.
[00:04:11] It almost sounds like a problem inversion, right?
[00:04:13] Instead of saying, here’s the thing I want to make,
[00:04:16] what do the materials need to be?
[00:04:18] You’re now saying, here are the materials, what should my project be?
[00:04:21] Yeah, exactly.
[00:04:22] It’s a thing that I think,
[00:04:24] is usually not productive in software,
[00:04:26] you know, going, here’s a new tool,
[00:04:28] what can I do with it?
[00:04:30] Instead of going, I have a problem I need to solve, what’s the best tool?
[00:04:33] That can be a bit of a blessing and a curse, right?
[00:04:35] The like, here’s a hammer, now go find a nail?
[00:04:38] Yeah.
[00:04:39] Sometimes people do like, out of left field,
[00:04:42] really creative things and you’re like, wow,
[00:04:44] I would never have thought to use it in that situation.
[00:04:47] And maybe that just is
[00:04:49] fun from a sort of creative expression side of things.
[00:04:51] Maybe it’s actually really useful and it unlocks something
[00:04:54] for the rest of the team or community
[00:04:56] because no one ever thought to
[00:04:58] use a tool in that situation before.
[00:05:00] Yeah, that’s true.
[00:05:01] But also sometimes you end up with like hype cycles where
[00:05:05] you know, there’s some shiny new hammer
[00:05:07] and then everybody wants to shove it into
[00:05:10] every new project.
[00:05:12] Exactly.
[00:05:13] What’s new in your world?
[00:05:15] Do you have a shiny new hammer?
[00:05:17] I wish I had a shiny new hammer.
[00:05:20] I spent a lot of this morning struggling with parsing,
[00:05:23] parsing imported CSV files in the app we’re using,
[00:05:26] which is…
[00:05:27] Okay.
[00:05:29] I feel like an eternal challenge just because,
[00:05:33] you know, CSV feels like such a simple file format.
[00:05:36] Until it isn’t.
[00:05:38] Until it isn’t.
[00:05:39] Until someone sends you an Excel file that they saved as CSV
[00:05:43] and there’s all kinds of encoding surprises.
[00:05:47] So I’ve been dealing with that one and I don’t know that it would be
[00:05:52] necessarily possible for anyone to write a parser or like software
[00:05:56] that uses a parser that can account for every possible way that a CSV
[00:06:00] is going to be weird.
[00:06:01] Right?
[00:06:02] So I’m kind of struggling with the like,
[00:06:04] how broad and how careful do I want to be?
[00:06:08] Right?
[00:06:09] Like how many different kinds of a weird CSV encoding or whatever
[00:06:13] else do I want to account for and take into consideration and handle
[00:06:19] versus, you know,
[00:06:21] if it’s not like this,
[00:06:23] then you just need to do something different with your file.
[00:06:26] Do you need to sort of change your processing pipeline to handle it?
[00:06:30] Or do you reject it and tell people,
[00:06:32] look, that’s your problem?
[00:06:34] Yeah, exactly.
[00:06:36] Considering the user base that we have,
[00:06:38] I think it’s very likely that almost every CSV that gets imported will be
[00:06:42] created via Google Sheets or Microsoft Excel.
[00:06:45] So I think if we can just sort of handle the most common things that will come
[00:06:49] out of those,
[00:06:50] that will probably be okay.
[00:06:52] I feel like Excel to CSV exports are notorious for all sorts of weird
[00:06:59] artifacts and encoding issues.
[00:07:01] They sure are.
[00:07:02] One that happens to me a lot is my name.
[00:07:06] So my name has an accent.
[00:07:08] Yeah.
[00:07:09] And oftentimes the encodings get broken when it goes through Excel.
[00:07:15] And this even happened to me once at a conference where,
[00:07:19] the badge with my name was printed.
[00:07:22] And instead of my letter with the accent on it,
[00:07:26] I just had some,
[00:07:27] a few gibberish characters that got printed on my actual conference badge,
[00:07:31] presumably because all of this had gone through a spreadsheet at some point.
[00:07:36] Yeah.
[00:07:37] I am lucky that in this case,
[00:07:39] the data that’s in the Excel or in the spreadsheet and the CSV is very
[00:07:44] standardized.
[00:07:45] It’s going to be numbers,
[00:07:46] dates and stock tickers.
[00:07:48] Okay.
[00:07:49] There’s not going to be accents.
[00:07:51] I’ve got some weird date formatting stuff.
[00:07:53] I’m trying to figure out that I think is actually less the CSV and more of
[00:07:56] the API we’re sending the data to.
[00:07:58] But,
[00:07:59] I know Excel can be weird with dates sometimes,
[00:08:01] and it will sort of try to assume that too many things are dates.
[00:08:05] So you put in other forms of data in a column and it’s just,
[00:08:09] it really wants to believe it’s a date and it will try to like transform it.
[00:08:12] Yeah.
[00:08:13] I feel like I’ve seen a lot of memes based on that.
[00:08:15] It can be pretty funny.
[00:08:16] Yeah.
[00:08:17] So that’s definitely a piece of it too.
[00:08:19] So,
[00:08:20] and I think the other thing that’s really fun is that I’m working on a
[00:08:23] laptop running Linux for this project.
[00:08:26] So I don’t,
[00:08:27] and there’s like a really locked down VPN.
[00:08:30] I don’t actually have access to either Microsoft Excel or Google sheets.
[00:08:35] So another fun constraint that will probably make me creative.
[00:08:41] Have you ever tried to debug an issue in production while switching between
[00:08:44] your error tracker,
[00:08:46] log viewer and APM tool?
[00:08:48] Maybe you know how painful it is when you can see the error,
[00:08:51] but can’t find the relevant logs or when you see slow performance,
[00:08:55] but it can’t connect to the root cause.
[00:08:58] Scout monitoring is the all in one platform built to make your life easier
[00:09:03] with log management,
[00:09:04] performance tracking and error monitoring coming soon.
[00:09:07] All of your data will be together at last.
[00:09:10] We’ll go from bug to fix in one place.
[00:09:13] The result,
[00:09:14] less context switching,
[00:09:15] faster debugging and monitoring that actually helps you ship code instead of
[00:09:19] distracting from it.
[00:09:21] No dev ops team,
[00:09:22] no problem.
[00:09:24] Scout works with your existing stack and gives you insights in five minutes,
[00:09:28] not hours.
[00:09:29] From bug to fix in one place at scoutapm.com.
[00:09:35] As you’re going through this and encountering novel problems,
[00:09:37] do you find yourself taking down a lot of notes about the thing or like maybe
[00:09:42] trying to capture some big lessons learned that you’ve learned?
[00:09:44] I want to be a person who can do that,
[00:09:51] but I have just never been good at taking notes and then remembering that those
[00:09:56] notes exist and referring to them.
[00:09:58] I think the closest I get is sticky notes everywhere.
[00:10:03] Okay.
[00:10:04] I have a few different colors and,
[00:10:06] you know,
[00:10:07] there’ll be a sticky note for a blog post I want to write or sticky note for a
[00:10:10] thing I need to do,
[00:10:11] something like that.
[00:10:12] But that’s about as close as I can get.
[00:10:13] That’s about as close as I get to taking good notes when I’m struggling with
[00:10:16] the problem.
[00:10:17] But I feel like this is the thing you’re pretty good at or have put a lot of
[00:10:20] work into developing a system for.
[00:10:22] Is that right?
[00:10:23] Yeah,
[00:10:24] I do a fair amount of it,
[00:10:26] not in all areas,
[00:10:27] but what I do have is a longer term,
[00:10:30] almost like mini wiki that I’ve created of ideas about software.
[00:10:35] The ideas are broken down into very small chunks,
[00:10:39] typically a thesis statement and a paragraph of supporting text.
[00:10:42] Maybe a diagram or a code sample.
[00:10:44] And then they interlink to each other pretty heavily.
[00:10:47] So oftentimes what I try to do is when I’m faced with a problem and I solved it,
[00:10:54] is to step back and say,
[00:10:55] is there a lesson I can take away from this?
[00:10:56] And if yes,
[00:10:57] maybe I can distill that down into something that can fit in that note taking
[00:11:01] system.
[00:11:02] I’m sort of inconsistent about how often I’m adding ideas there.
[00:11:07] Sometimes I’m adding like five or six at a time and then it’s a couple of weeks
[00:11:11] and I don’t touch the system and then I come back.
[00:11:14] But I try to at least be sort of a little bit more mindful of the work that I’m doing
[00:11:20] and trying to extract lessons out of it.
[00:11:22] What tool do you use for that system?
[00:11:24] Because the sort of interlinking that you mentioned sounds very useful,
[00:11:27] but difficult to do with sticky notes.
[00:11:29] The old fashioned way of doing it,
[00:11:31] if you’re using sticky notes or note cards,
[00:11:33] is you have a numbering system.
[00:11:35] So every note has effectively an incrementing ID or something like that.
[00:11:40] And then when you want to link a card to another one,
[00:11:43] you just say,
[00:11:44] see note number and then you give it a number.
[00:11:46] And then that is how you sort of cross index.
[00:11:49] That’s cool.
[00:11:50] Is that what you do?
[00:11:51] So I don’t do use physical notes.
[00:11:53] I use a digital system.
[00:11:55] I use Obsidian as the program,
[00:11:57] but there are others out there as well.
[00:12:00] I think it’s the sort of newest generation of note taking apps have pretty much all
[00:12:04] converged on the idea of hyperlinking notes being a good thing.
[00:12:07] I’m kind of strict with it though,
[00:12:09] and then I don’t put like temporary notes,
[00:12:12] random sort of half form thoughts.
[00:12:15] You know,
[00:12:16] I don’t put just tracking my debugging journey.
[00:12:19] Like, oh, remember this function here is branching there.
[00:12:21] Like all that kind of thing.
[00:12:22] I might take notes for those things,
[00:12:24] but that stays separate from my sort of little mini personal Wiki.
[00:12:28] Do you have a different system for those or is it just sort of ad hoc writing down what you need to?
[00:12:33] It is ad hoc.
[00:12:34] I wish I were more sort of organized and disciplined for those.
[00:12:37] I will oftentimes,
[00:12:38] I will oftentimes create maybe a separate Obsidian vault,
[00:12:41] just sort of track things down there.
[00:12:43] Sometimes it’s just like a notebook or a scratch pad or something like that.
[00:12:48] If I’m going through debugging and I just need to leave breadcrumbs for myself
[00:12:52] or sort of capture the outcome of what I’m trying to understand.
[00:12:56] Someone I was working with recently showed me that they had a setup for basically tracking every project they’ve done,
[00:13:03] you know,
[00:13:04] because we’re consultants and we’re working on many different projects over time.
[00:13:07] They had noted sort of like what the project was and what technologies they used and maybe even accomplishments for that time along with dates.
[00:13:17] And so could refer to sort of like a history of work that they’ve done,
[00:13:21] which I found really inspiring and also really intimidating the idea of building.
[00:13:26] Yeah.
[00:13:27] But it was,
[00:13:28] it looked really useful and I don’t do any sort of tracking like that.
[00:13:31] Yeah.
[00:13:32] I feel like that would be really helpful if you’re ever having to like,
[00:13:36] try to go back to lessons learned from a particular situation,
[00:13:40] or even when you’re just trying to look back and get a sense of like,
[00:13:43] Oh,
[00:13:44] what have I done in the last few years?
[00:13:45] What is my professional growth looking like?
[00:13:47] I feel like the sort of interview style questions,
[00:13:50] you know,
[00:13:51] tell me a time when,
[00:13:52] you know,
[00:13:53] you had to deal with an outage or something like that.
[00:13:55] My mind always freezes and I’m like,
[00:13:57] uh,
[00:13:58] I can know that I’ve done a bunch of these,
[00:14:00] but I can’t think of any concrete example right now.
[00:14:03] Yeah.
[00:14:04] It would be so useful to,
[00:14:05] to be able to pull up your own little brain record.
[00:14:09] How do you feel about journaling either for like a sort of work related sort of
[00:14:16] code stuff or even just like your own personal life?
[00:14:19] Is that a thing that you try to do?
[00:14:21] I have tried it a few times in my life and it’s never really stuck.
[00:14:25] I think I tend to get caught up in like trying to decide the perfect level of
[00:14:31] detail and how perfect do I want it to be?
[00:14:34] And like,
[00:14:36] I just get really in my head about like what I’m doing instead of just writing things down.
[00:14:42] And then I get frustrated and give up.
[00:14:45] I have had jobs in the past where we sort of had to do like a pseudo journal of like just a little paragraph about our day at the end of every day.
[00:14:54] It’s like the Elon Musk style.
[00:14:56] Tell me five things you did this week.
[00:14:58] Yeah.
[00:14:59] Yes.
[00:15:00] And I think,
[00:15:01] you know,
[00:15:02] anytime there’s like an enforced system like that,
[00:15:03] it just kind of ends up being not very useful because you just kind of are checking the box.
[00:15:10] What about you?
[00:15:11] Do you do any journaling?
[00:15:12] I do not.
[00:15:13] Don’t do any journaling for personal life.
[00:15:15] For a while I was keeping TIL doc,
[00:15:18] Today I Learned.
[00:15:19] I even had like a Vim shortcut for it so that I could just sort of hit a keyboard command,
[00:15:26] start typing,
[00:15:27] and that would add an entry to my TIL doc.
[00:15:30] And I wasn’t using that consistently enough.
[00:15:32] So I think that’s sort of the closest thing that approximates journaling.
[00:15:36] I know a lot of modern note-taking apps,
[00:15:40] one of the sort of things that became trendy was the idea of a daily note that acts sort of like journaling,
[00:15:47] but that could be tailored to some sort of maybe reflection.
[00:15:53] Let’s say at the end of the day,
[00:15:54] you write down some things,
[00:15:55] some reflections from your day,
[00:15:56] or maybe even throughout the day,
[00:15:57] you’re like,
[00:15:58] huh,
[00:15:59] I encountered a new method I never used,
[00:16:00] or like any sort of like little,
[00:16:01] thing like that,
[00:16:03] which might then allow you to go back and treat that as source material for a bigger idea,
[00:16:08] something that might fit in my,
[00:16:09] in my Wiki.
[00:16:10] But I don’t do any of that.
[00:16:12] Yeah.
[00:16:13] These are all sort of like note-taking is like a long-term practice.
[00:16:19] But what about recording notes and thoughts as you’re working through a problem?
[00:16:25] So less reflecting on it later,
[00:16:28] but more like I am trying to design a thing,
[00:16:30] or debug a thing,
[00:16:32] maybe make a diagram of a thing.
[00:16:34] Yeah,
[00:16:35] I do a lot of diagramming as a way to get my thoughts out of my head.
[00:16:40] So that’s definitely,
[00:16:41] it’s not quite the same thing as note-taking,
[00:16:44] but I think it does hit a lot of the similar values.
[00:16:48] Do you keep those?
[00:16:49] Like,
[00:16:50] is there a system for storing those and reflecting back on them or using them for future problems?
[00:16:56] Or is it sort of an ephemeral,
[00:16:58] this is helping me now,
[00:16:59] archiving?
[00:17:00] It’s a mix.
[00:17:01] Sometimes it’s ephemeral.
[00:17:03] Sometimes I will keep a copy or a screenshot of the diagram
[00:17:07] if it was particularly interesting to share with other people
[00:17:10] or to use as examples in other situations.
[00:17:13] I’ve even done situations where I’ve created an ASCII version of the diagram
[00:17:17] and embedded it in my commit message.
[00:17:19] Oh, that’s nice.
[00:17:20] If it’s particularly relevant.
[00:17:22] It’s been a little while since I’ve used it,
[00:17:25] but MonoDraw is a tool for macOS.
[00:17:28] That allows you to just draw shapes and diagrams as ASCII,
[00:17:34] and that makes it really easy to have something you can copy paste into a commit message.
[00:17:39] Yeah, that’s really cool.
[00:17:41] I hadn’t thought of doing a diagram in a commit message.
[00:17:43] I feel like sometimes commit messages are actually the closest I get to any sort of journaling.
[00:17:48] Yeah, that’s true.
[00:17:49] You can look back through your commits in a day and sort of see what happened,
[00:17:54] for better or for worse.
[00:17:56] Are you the kind of person that does a lot of work,
[00:17:57] and progress commits,
[00:17:59] sort of all the little steps,
[00:18:01] and then maybe cleans it up at the end of the day?
[00:18:04] Absolutely.
[00:18:05] I remember distinctly maybe my first or second PR ever
[00:18:09] when I was working as a developer.
[00:18:11] I hadn’t learned about rebasing or squashing or anything like that,
[00:18:15] and the PR was dozens of commits that were all like,
[00:18:18] whoops, or try again.
[00:18:20] But generally, if I’m very frustrated,
[00:18:25] getting the same error message or something,
[00:18:27] or just can’t get something to work,
[00:18:28] and then I get a bit of progress,
[00:18:30] new error message,
[00:18:31] or something is working a little bit better,
[00:18:33] I’ve trained myself pretty well to think of that as a moment to make a commit.
[00:18:37] Because so often if I don’t and keep going,
[00:18:42] I will somehow undo that progress I just did
[00:18:45] and not be able to get back to it and be like,
[00:18:47] I know that 30 minutes ago this was working,
[00:18:50] and now I’ve done something and it’s not working anymore,
[00:18:53] and I didn’t make a commit at that point,
[00:18:55] so I don’t really have a good way other than,
[00:18:58] you know,
[00:18:59] control Z and cross my fingers to getting back to what was working before.
[00:19:03] So I like to do a commit anytime I’ve got a little bit of progress to celebrate.
[00:19:09] When I’m pairing with someone,
[00:19:11] if we ever have a moment where somebody goes,
[00:19:13] yay or oh,
[00:19:14] it works or something like that,
[00:19:15] I go,
[00:19:16] okay, commit.
[00:19:17] And then,
[00:19:18] you know,
[00:19:19] anytime I’m,
[00:19:20] I like to commit at the end of the day,
[00:19:21] even if I don’t have a good stopping point or like a progress,
[00:19:23] but I don’t,
[00:19:24] I don’t like to walk away at the end of the day with uncommitted changes on my local machine.
[00:19:31] Is this committing specifically and then pushing to another repository?
[00:19:35] At the end of the day,
[00:19:36] it usually is.
[00:19:37] Yeah.
[00:19:38] During the day,
[00:19:39] if I’m,
[00:19:40] you know,
[00:19:41] just making little bits of progress,
[00:19:42] I don’t always push that up.
[00:19:43] Sometimes I do,
[00:19:44] you know,
[00:19:45] if I want to see,
[00:19:46] like,
[00:19:47] how does this look on CI?
[00:19:48] Works on my machine,
[00:19:49] but…
[00:19:50] But that committing at the end of the day is specifically because you’re trying to mitigate
[00:19:53] the risk of,
[00:19:54] oh,
[00:19:55] no,
[00:19:56] my dog at my laptop or something.
[00:19:57] Yeah.
[00:19:58] Or I’m unexpectedly out and I can message a coworker and be like,
[00:20:00] I’ve got a branch.
[00:20:01] If you’re able to pick it up and keep going,
[00:20:02] ideally,
[00:20:03] you know,
[00:20:04] in a,
[00:20:05] in a perfect world,
[00:20:06] the commit would also indicate where I am and what’s next,
[00:20:07] but…
[00:20:08] Right.
[00:20:09] Right.
[00:20:10] Yeah.
[00:20:11] I think I’ve seen like a t-shirt or whatever,
[00:20:12] which is like in case of fire,
[00:20:13] get commit,
[00:20:14] get push.
[00:20:15] I like that.
[00:20:16] And,
[00:20:17] you know,
[00:20:18] I’ve never,
[00:20:19] you know,
[00:20:20] I’ve never,
[00:20:21] you know,
[00:20:22] and,
[00:20:23] you know,
[00:20:24] I’ve never actually had a building I’m working at catch on fire,
[00:20:26] but just the idea of like,
[00:20:28] you don’t necessarily know what’s going to happen tomorrow.
[00:20:31] So you do a lot of little sort of work in progress commits throughout the day.
[00:20:35] And that maybe gives you a sense of like what the path was to get to the end of the feature.
[00:20:40] Do you tend to then squash at the end?
[00:20:42] Or do you like to keep that,
[00:20:43] that journey permanently in the record?
[00:20:46] I tend to do at least some squashing.
[00:20:49] I don’t find a lot of value in like a string of commits that were like,
[00:20:52] you know,
[00:20:53] linter fix or update test with different data or whatever.
[00:20:57] It’s not,
[00:20:58] you know,
[00:20:59] if the commits aren’t meaningful,
[00:21:00] I think it’s worth squashing.
[00:21:01] I think if the commits are kind of meaningful as far as like this bit,
[00:21:06] you know,
[00:21:07] if I’m working on a full feature that I might have a commit that is like
[00:21:10] setting up the migration and the model or a commit that is like the controller
[00:21:14] and the controller specs or something like that,
[00:21:16] if they represent meaningful,
[00:21:18] distinct pieces of work,
[00:21:20] then I think it makes sense to keep the commits.
[00:21:21] But when it’s really just a journey of me struggling and succeeding
[00:21:27] and then finding a new error and then succeeding
[00:21:29] and messages that aren’t necessarily going to be meaningful to anybody else,
[00:21:33] I don’t feel the need to keep those.
[00:21:35] Yeah.
[00:21:36] I find that I tend to like my history on main to sort of be like,
[00:21:42] I do want them sort of atomic and discreet.
[00:21:44] Like these commits should be self-contained,
[00:21:46] but ideally they’re kind of as small as they can be in terms of like this adds
[00:21:50] one little slice of the feature,
[00:21:52] or this is doing a refactor that sets up some other work,
[00:21:54] but it’s distinct so that I can just scroll through the commits and see the
[00:21:59] full story of what’s happening in the app.
[00:22:02] I know a lot of teams like to just sort of keep all the like in progress
[00:22:05] commits and do merge commits,
[00:22:08] which can make the history sort of ugly to read.
[00:22:12] And oftentimes also means that the descriptions are really bad on the
[00:22:17] individual commits.
[00:22:18] So you’re sort of stuck,
[00:22:19] heading to GitHub and having to read the PRs.
[00:22:22] If you want to get a sense of what was happening,
[00:22:24] you can’t just get that from the Git log.
[00:22:27] Yeah.
[00:22:28] How often do you find yourself reading Git history?
[00:22:31] Is that a thing that’s like you do often enough to think there’s value in?
[00:22:35] Oh, all the time.
[00:22:36] All the time?
[00:22:37] All the time.
[00:22:38] I use VS code and I’ve got an extension that like when you click on a line,
[00:22:42] it will show you what commit it’s from.
[00:22:45] And I find that so,
[00:22:46] so valuable to be like,
[00:22:48] this looks weird to me.
[00:22:50] Why is this weird?
[00:22:52] It’s probably a good reason.
[00:22:54] And then being able to look at the commit and go,
[00:22:56] okay, well this is part of this refactor.
[00:22:59] And this commit message actually explains why this weird thing happened.
[00:23:04] Or this commit message doesn’t explain why this weird thing happened,
[00:23:08] but it does tell me that Joel did it.
[00:23:10] So I can go talk to Joel if he’s around and,
[00:23:12] and get some clarity on it.
[00:23:14] Yeah.
[00:23:15] I love Git history spelunking.
[00:23:17] I think of it as,
[00:23:18] as a little bit.
[00:23:20] Yeah.
[00:23:21] And,
[00:23:22] and then sometimes also going to the PR and seeing the description there and
[00:23:24] what other files were changed and things like that.
[00:23:27] I find it so,
[00:23:28] so useful.
[00:23:29] So I get,
[00:23:30] I get very frustrated when a commit doesn’t actually say anything meaningful.
[00:23:35] I think my least favorite is a commit that just has the ticket number.
[00:23:38] Oh yeah.
[00:23:39] Yeah.
[00:23:40] And then I can’t even go to the PR.
[00:23:42] I have to go to the ticketing system that we work on and,
[00:23:44] and see what it was there,
[00:23:46] which actually brings me to another one.
[00:23:47] Kind of like sort of,
[00:23:48] sort of note taking,
[00:23:49] I guess more documentation in general is like the,
[00:23:50] the trail of comments on a ticket or issue that you’re working on.
[00:23:51] I have strong thoughts about this,
[00:23:52] but what are your thoughts about like,
[00:23:53] if you are working on a ticket and you have questions or need clarification,
[00:23:54] how do you approach that?
[00:23:55] It depends on,
[00:23:56] I think some of the sort of social norms of the team.
[00:23:57] On a smaller team,
[00:23:58] oftentimes the,
[00:23:59] the,
[00:24:00] the,
[00:24:01] the,
[00:24:02] the,
[00:24:03] the,
[00:24:04] the,
[00:24:05] the,
[00:24:06] the,
[00:24:07] the,
[00:24:08] the,
[00:24:09] the,
[00:24:10] the,
[00:24:11] the,
[00:24:12] the,
[00:24:13] the,
[00:24:14] the,
[00:24:15] the,
[00:24:16] the,
[00:24:17] the,
[00:24:18] the,
[00:24:19] the,
[00:24:20] the,
[00:24:21] the,
[00:24:22] the,
[00:24:23] the,
[00:24:24] the,
[00:24:25] the,
[00:24:26] the,
[00:24:27] the,
[00:24:28] the,
[00:24:29] the,
[00:24:30] the,
[00:24:31] the,
[00:24:32] the,
[00:24:33] the,
[00:24:34] the,
[00:24:35] the,
[00:24:36] the,
[00:24:37] the,
[00:24:38] the,
[00:24:39] the,
[00:24:40] the,
[00:24:41] the,
[00:24:42] the,
[00:24:43] the,
[00:24:44] the,
[00:24:45] doing it on the ticket it’s a little bit then like the context gets lost because it’s not on
[00:24:51] the ticket for someone else to see but it’s a little bit more non-blocking for me and on a
[00:24:56] smaller team i think that that pattern works well on a larger team or one that’s a little bit more
[00:25:02] process oriented doing it on the ticket is often the way to go i think it also sort of depends
[00:25:08] where the person you’re asking the question of tends to like what apps they live in during the
[00:25:14] day right if it’s someone who’s like always got jira open constantly working in jira then that’s
[00:25:19] probably going to be the fastest way to hear from them or if they live in email right yeah i’m the
[00:25:25] kind of person who monitors slack pretty closely but only checks email a few times a day which
[00:25:32] means that my sort of patterns for responding to things are going to be different than someone
[00:25:38] who’s you know sort of constantly on top of their email and like what notifications you have set up
[00:25:43] do you have
[00:25:44] you
[00:25:44] do you get notifications from github every time someone comments on something you’re working on
[00:25:48] or do you actively go look for those at when you’re ready to look at them i do feel strongly
[00:25:54] though that if you ask like asking for clarification on something in a space that
[00:25:59] isn’t where you’re tracking the work like i’m just going to say jira but jira will mean everything
[00:26:04] but that’s just because i’m using jira my project right now i almost always want to go back and
[00:26:09] then summarize that conversation or at least the output of that conversation
[00:26:14] on the ticket itself which is for other team members but it’s also very much for me you know
[00:26:20] i’m going to take a long weekend and come back and have absolutely no memory of what the answer
[00:26:27] to that was or yeah recently i had i was halfway through a feature when it got deprioritized
[00:26:33] because we were coming up to a deadline and so i just dumped everything i could think of about
[00:26:39] what i had finished and what i hadn’t finished and what was still a problem on to the next step
[00:26:44] that ticket and then moved on to something else and then just picked it back up now and i think
[00:26:49] it had been three months since i had worked on it last and i was so grateful for those notes i had
[00:26:55] taken when there are sort of edge case conversations like that that happen do you tend to also document
[00:27:01] that in the commit message the like uh we considered having the behavior be x but we
[00:27:08] ended up deciding it that we wanted to do y i do that occasionally
[00:27:12] if it’s
[00:27:14] a
[00:27:14] a case where like x seems like the really obvious way to go but we did y instead for good reasons
[00:27:20] or for reasons that felt seemed good at the time i think that’s worth documenting in a commit
[00:27:25] message i think when it’s more along the lines of like clarifying requirements or straightforward
[00:27:31] decisions i find those less useful to copy into the commit message i find that i’ll put oftentimes
[00:27:39] things where i’m trying to preempt a potential reviewer asking a question
[00:27:42] so
[00:27:44] like why are we doing it like this doesn’t our app normally work like this those sorts of things
[00:27:49] typically make it into the commit message yeah absolutely i think if you’re deviating from a
[00:27:54] convention that’s like app wide or or just industry wide i think that’s really important
[00:28:00] to note in a commit message so you mentioned that better note taking is the thing that’s
[00:28:05] aspirational for you what are the aspects that you find are aspirational or things or benefits
[00:28:11] you’re hoping to get out of it because i think people approach note taking as a thing that’s
[00:28:13] note-taking with a whole lot of different motivations? Yeah, that’s a great question.
[00:28:20] For me, I think it is remembering things that I’ve done before. I use command history in the
[00:28:26] terminal so often to try to figure out, I know there’s a way to do this, and I know the command
[00:28:32] has this word in it, so I will search my command history to figure out the way that I have done
[00:28:37] this before. And almost every time that I do that, I think I should really alias this or
[00:28:43] record it somewhere, because your command history is only so long, and it’s all local, and
[00:28:51] can’t find it. Things that I do just often enough to repeat them, but not often enough to remember
[00:28:58] them, or things that I’ve learned that I think are worth either sharing with someone else
[00:29:04] or recording for myself so I don’t have to relearn it in the future, for sure.
[00:29:11] So for you, it’s a…
[00:29:13] Almost like an aid for memorization.
[00:29:15] Yeah, I think, yeah, absolutely. Because I can be very forgetful. I can remember
[00:29:21] numbers, but not tasks and things like that. And I think also to aid in reflection.
[00:29:29] If someone will ask me, like, how’s your project going? I can tell them, you know,
[00:29:35] this is how I feel about it in the moment. But I would like to be able to have some sort of
[00:29:39] documentation for, like, what has happened, what has been…
[00:29:43] What has been good, what has been frustrating. Because, you know, on a day when you’ve just had
[00:29:46] a really frustrating interaction with a teammate or reviewed a really disappointing PR, it can make
[00:29:54] you feel like this whole project is garbage. But I know that in reality, that one day is
[00:29:59] overshadowing maybe, you know, three or four weeks of great. And so having, like, documenting how
[00:30:04] things are going, I think can give me a more, I don’t want to say objective, but more holistic or
[00:30:12] long-term view.
[00:30:13] Of what’s been happening.
[00:30:14] I feel like there’s also a part of it, though, that is like, I just feel like I should take notes more.
[00:30:20] Yeah, like, part of being a cool developer, or maybe even just a, you know, adult who’s got
[00:30:29] got it together is taking notes. It’s an aspirational thing, because it’s a marker of
[00:30:34] having made it.
[00:30:36] Yeah, yeah. Or it’s just like a thing that people do.
[00:30:41] When I joined ThoughtBot,
[00:30:43] I got, you know, first day, there’s like a little swag, like a sticker and a t-shirt,
[00:30:48] and also a little Moleskine notebook. And I definitely have teammates who have gone
[00:30:53] through so many of those since they started. I am six and a half years in and about two-thirds
[00:31:01] of the way through my first one. So in a way, it is kind of an interesting reflection of like,
[00:31:06] like, the notes are not super meaningful now. It’s more just, I use that when I need to jot
[00:31:10] something down. But looking back, back, back, back, back, back, back, back, back, back, back, back,
[00:31:13] I can be like, oh, yeah, I remember that project. And when I was like, working on that problem,
[00:31:17] or something like that. But yeah, it almost feels like I’m embarrassed to admit that I have
[00:31:24] written down that you’re not a note taker,
[00:31:28] 70 pages of things.
[00:31:30] I feel like I’m sort of one foot in both camps and that I’m not a regular note taker. I don’t
[00:31:36] feel like I take notes the way a lot of people take notes. But because I have this like mini
[00:31:41] personal wiki of like,
[00:31:42] deeper software thoughts, it means that I can be in a conversation in Slack with a teammate,
[00:31:48] and they mentioned a problem. I’m like, oh, I have a note about that. Or a couple of notes,
[00:31:52] I can pull together what’s almost a mini blog post on a lot of different topics sort of at will.
[00:31:58] And so that gives that sort of impression of like, wow, you’ve got something super cool going on.
[00:32:03] And you’ve really got it together, even though like,
[00:32:06] it does give that impression. That is what I believed about you, Joel.
[00:32:11] It’s all,
[00:32:12] it’s all an illusion.
[00:32:15] Back to your D&D character.
[00:32:17] Uh-huh.
[00:32:18] I don’t take notes, but I give the illusion of taking notes.
[00:32:21] So for me, it was a way to help build more intentional growth,
[00:32:26] do some deeper thinking about software, and then build connections between ideas.
[00:32:31] And it’s turned out that this style of note has been really helpful for building content.
[00:32:37] Like I said, I can sort of almost throw together a little impromptu blog post on all sorts of topics,
[00:32:42] because I can string together two or three notes that are already written in prose,
[00:32:45] already have a code example.
[00:32:47] So that helps me when I’m actually trying to blog.
[00:32:49] When I’m conference season, and I’m trying to find ideas to submit to a CFP.
[00:32:55] Even sometimes when I’m trying to put together a list of topics for the bike shed,
[00:32:59] and like, oh, what are we going to talk about next week?
[00:33:01] I can like scroll through some of those notes and be like, oh, that would be a good idea.
[00:33:04] Yeah, all of those are places that I, yeah, those are reasons I want to take,
[00:33:09] be better at taking notes.
[00:33:10] Because I often,
[00:33:11] I feel like I have good ideas for blog posts, and I’ll jot them down or not jot them down.
[00:33:16] And then when I go to write them, it’s like this immense task trying to
[00:33:20] get my brain back into the context of where it was when I had that thought.
[00:33:25] I also have never actually spoken at a conference.
[00:33:28] I’ve submitted a couple of proposals that haven’t been accepted.
[00:33:32] And, you know, while I was submitting them, I was like, this doesn’t feel like the best I can do.
[00:33:37] But it is the best I can do with what I’ve got right now.
[00:33:41] Right, right.
[00:33:43] I know some people keep a sort of note document of just ideas they got excited about throughout the year,
[00:33:48] so that when conference season comes, they have a list of things they can pitch from.
[00:33:54] And I guess in that sense, it is a note.
[00:33:57] It’s different from what I’m doing, but it definitely fulfills a similar function.
[00:34:01] Yeah, absolutely.
[00:34:02] Is your collection of notes sort of how you wound up writing a book?
[00:34:08] I think it helped me do a lot.
[00:34:11] I think it helped me do a lot.
[00:34:11] I think it helped me do a lot.
[00:34:11] I think it helped me do a lot of content in general,
[00:34:12] and that that gave me the confidence to be like, oh, yeah, I could write a book.
[00:34:16] The inspiration behind writing a book is really just a lot of interactions I had with people
[00:34:21] when I was spending a lot of time in a few different sort of Slack groups online,
[00:34:28] helping people out, answering the same questions over and over.
[00:34:31] I’d also been part of a few mentorship projects and, again, answering questions.
[00:34:35] So the genesis of the book, which for those who have not heard of this before,
[00:34:41] I’m in the process of writing a book on the fundamentals of web development,
[00:34:45] focusing on the web platform itself, so not the languages,
[00:34:48] but understanding how the web works, what are the big ideas,
[00:34:52] and how that impacts what you can build.
[00:34:55] And so the idea of looking at the web through this platform lens
[00:34:58] came out of helping people who were stuck, a lot of them more junior,
[00:35:04] and realizing that, oh, there’s some pieces missing in this sort of mental puzzle
[00:35:10] of how to build a platform.
[00:35:10] Of how the web works.
[00:35:12] And because that piece is missing, they don’t have enough of the full picture
[00:35:16] to be able to get themselves unstuck in this situation.
[00:35:19] Have you found yourself taking a lot of notes or taking notes in a new way
[00:35:24] as you write the book?
[00:35:25] Yes.
[00:35:26] So part of the approach that I use is the idea that any creative work you create
[00:35:32] is going to have byproducts.
[00:35:34] So I write a talk, I write a blog post, or I’m writing a book.
[00:35:39] Some things make it into the book,
[00:35:40] and some things are really good, but I have to cut them
[00:35:42] because they don’t fit the narrative that I’m following in this particular situation.
[00:35:47] That’s not junk.
[00:35:48] That can be really valuable.
[00:35:50] And so I can recycle it for some other time.
[00:35:52] But maybe it starts its life as just a note in my note-taking system.
[00:35:57] And then from there, it can then grow into something else.
[00:36:01] Another form of, I guess, byproduct that doesn’t necessarily get cut,
[00:36:05] but the book relies a lot on a talk about mental models.
[00:36:09] Yeah.
[00:36:09] And so we did an episode a while back where we talked about a few different mental models
[00:36:13] that I have for answering the question, what is a web browser?
[00:36:17] What does it do?
[00:36:18] And so I’ll have notes for mental models.
[00:36:20] Mental models are a thing that I find really powerful, and I like to collect them.
[00:36:24] Yeah.
[00:36:25] And so most of the mental models that are in the book
[00:36:28] either start as notes in my note-taking system,
[00:36:31] or if I discover them while writing,
[00:36:33] then I’ll extract them and put them in my note-taking system as well.
[00:36:37] I feel like we have…
[00:36:39] Coming up, our sort of first wrap-up episode for,
[00:36:42] I guess, the first sort of seasonal version of The Bike Shed.
[00:36:44] Yeah.
[00:36:45] Where we are hoping to sort of recap, look back over the season,
[00:36:49] talk about things we’ve learned, ways we’ve grown,
[00:36:52] things we’ve tried and maybe had success or failure with.
[00:36:56] And maybe something that I could introduce as part of my contribution to
[00:36:59] that regular episode is just a look back and like,
[00:37:03] hey, what’s one or two interesting ideas that made it into my note-taking system
[00:37:06] over this past season?
[00:37:08] Yeah.
[00:37:09] I would love to hear that.
[00:37:11] And I feel like that sort of thing is another reason
[00:37:13] I kind of wish I was better at taking notes.
[00:37:16] As far as reflecting on the season,
[00:37:19] I’ll find a way to reflect without the notes that I haven’t taken.
[00:37:25] I think many sort of regular listeners might notice
[00:37:28] that a lot of things that end up in my notes
[00:37:30] will often end up as well in when I talk about what’s new in my world.
[00:37:35] Because I might have an idea that’s percolating in my mind,
[00:37:37] like, oh, I’m excited about this.
[00:37:39] I’m excited about this mental model,
[00:37:39] or I’m excited about this idea about thinking about uncertainty in programs
[00:37:44] or whatever the particular thing is.
[00:37:47] As we wrap up, I’d like to point our listeners
[00:37:50] to a couple of articles that I’ve written.
[00:37:52] We’ll share them in the show notes.
[00:37:54] One, just about being more self-aware,
[00:37:58] trying to examine your experience,
[00:38:01] the work that you do day-to-day to extract learning out of it.
[00:38:05] This is something that I do to try to have this sort of continual growth,
[00:38:09] mindset as I’m just doing regular feature work every day.
[00:38:14] Note-taking is one part of that,
[00:38:15] but that’s sort of the broader mindset that I use that motivates note-taking.
[00:38:20] So I wrote a little bit about that.
[00:38:22] There’s some other techniques I share there, so I’ll link to that.
[00:38:25] And then there’s an article where I go more in-depth about
[00:38:27] my personal note-taking system
[00:38:29] and the mechanics of how I break things down and all that.
[00:38:33] So for all the listeners who are like,
[00:38:34] oh, you sort of teased a little bit of like a wiki thing,
[00:38:36] but like, exactly how does it work?
[00:38:39] It’s all written down there.
[00:38:40] So we’ll link to that as well.
[00:38:42] Awesome.
[00:38:43] Yeah, I think I’ve read those before,
[00:38:45] but I’m excited to go dig into them again
[00:38:47] and maybe take some notes.
[00:38:48] On that note, shall we wrap up?
[00:38:52] Yep, absolutely.