497: Diagrams we love
Episode
41 min
Read time
2 min
Topics
Relationships, Design & UX, Artificial Intelligence
AI-Generated Summary
Key Takeaways
- ✓Denormalized Control Flow Trees: Convert standard control flow diagrams into trees by never merging branches back together. Each downstream decision point gets duplicated across every branch. This makes combinatorial path explosions visually obvious — two independent inline conditionals in Ruby produce four distinct code paths, revealing untested scenarios that a classic merged flowchart would obscure entirely.
- ✓Flowcharts as Test Maps: Structure flowcharts with a single entry state at the top and all terminal states at the leaf nodes. Every leaf node maps directly to a required unit test. This technique works in commit messages using ASCII art flowchart tools, giving reviewers an immediate visual inventory of what test coverage the code demands.
- ✓Sequence Diagrams for Multi-Party Auth Flows: Use sequence diagrams specifically when three or more actors exchange messages — client, server, and a third-party OAuth provider. Diagramming each round trip explicitly uncovers overlooked server-client exchanges that developers mentally glossed over, answering the concrete question: how did the server know that client action occurred?
- ✓State Machine Diagrams Across Disciplines: Map UI components as state machines — listing every state, every user action, and every transition arrow — to force conversations about error states, loading states, and blur events before writing code. Sitting with a designer to build this collaboratively converts vague product requirements into a structured, shared decision record that resolves edge cases upfront.
- ✓LLM-Generated Mermaid Diagrams as Code Lenses: Prompt an LLM to generate Mermaid diagrams scoped by model and depth — for example, an ERD starting from the User model at depth two, or a call graph tracing a function three levels deep. GitHub natively renders fenced Mermaid blocks in PRs with pan and zoom, making complex changes scannable without prose explanation.
What It Covers
Joel Kenville and Adji Slater of Thoughtbot explore five diagram types — flowcharts, denormalized control flow trees, sequence diagrams, state machine diagrams, and dependency graphs — examining how each one surfaces hidden complexity, exposes untested code paths, and improves communication across development and design disciplines.
Key Questions Answered
- •Denormalized Control Flow Trees: Convert standard control flow diagrams into trees by never merging branches back together. Each downstream decision point gets duplicated across every branch. This makes combinatorial path explosions visually obvious — two independent inline conditionals in Ruby produce four distinct code paths, revealing untested scenarios that a classic merged flowchart would obscure entirely.
- •Flowcharts as Test Maps: Structure flowcharts with a single entry state at the top and all terminal states at the leaf nodes. Every leaf node maps directly to a required unit test. This technique works in commit messages using ASCII art flowchart tools, giving reviewers an immediate visual inventory of what test coverage the code demands.
- •Sequence Diagrams for Multi-Party Auth Flows: Use sequence diagrams specifically when three or more actors exchange messages — client, server, and a third-party OAuth provider. Diagramming each round trip explicitly uncovers overlooked server-client exchanges that developers mentally glossed over, answering the concrete question: how did the server know that client action occurred?
- •State Machine Diagrams Across Disciplines: Map UI components as state machines — listing every state, every user action, and every transition arrow — to force conversations about error states, loading states, and blur events before writing code. Sitting with a designer to build this collaboratively converts vague product requirements into a structured, shared decision record that resolves edge cases upfront.
- •LLM-Generated Mermaid Diagrams as Code Lenses: Prompt an LLM to generate Mermaid diagrams scoped by model and depth — for example, an ERD starting from the User model at depth two, or a call graph tracing a function three levels deep. GitHub natively renders fenced Mermaid blocks in PRs with pan and zoom, making complex changes scannable without prose explanation.
Notable Moment
While implementing a type-ahead component in Elm, the type system forced discovery of unhandled UI states. The developer and designer then spent hours building what looked like annotated mockups with arrows — only to realize they had accidentally constructed a formal state machine diagram without using any standard diagramming terminology.
Episode Transcript
Hello, and welcome to another episode of The Bike Shed, a weekly podcast from your friends at Thoughtbot about developing great software. I'm Joel Kenville. And I'm Adji Slater. And together, we're here to share a little bit of what we've learned along the way. So, Adji, what's new in your world? New in my world is I'm starting work on a new talk. It's going to be at Haggis Ruby at the April. That is the Scottish Ruby Convention. I have to say that is a delightful name for a conference. I enjoy it as well. It's the tastiest Ruby conference, and the little haggis mascot that is on the website is truly wonderful. I love it so much. And, yeah, I don't know the detail, the fine lines of the shape of this talk just yet. It was a little bit talk about something that's on your mind and kind of fitting the theme of the conference. It's about building things for, at least from from my perspective, building things from that that kind of part of yourself that's like fed by creativity and like nurtured by making and building and doing things for the the sake of fulfilling that. I kind of think a human need, but don't know the ins and outs of it too much. I think there's gonna be a little bit of, like, my recent time exploring around with Dragon Ruby and what are the differences between game development and web development. But speaking only as, like, a hobbyist game developer, then, yeah, there's there's something there. But I don't know exactly what it is just yet. Do you think you're making an argument for sort of side projects as creative outlet? Or is the idea to find a way to make your day job scratch that creative itch? Maybe a little both. I, yeah, I go back and forth because there are certainly times when I really buck against the trend of making your side project monetizable or, like, the thing that you get your creative itch taken care of with doesn't have to be your career. But, also, like, your career should be rewarding and fulfilling and and all these different things as well. So, yeah, like I said, I haven't really kind of dialed in on it a 100% of the way. But a little bit like we were talking about a little while ago, I think, is, that kind of, like, playfulness and that enjoyment and kind of excitement and energy from from those sort of purely creative or, sort of purely exploratory parts of making and building and and what we do. I think that's something that the Ruby community is really good at tapping into, that sort of joy and almost, like, sort of creative weirdness. And I think it's RubyConf this year that has a track for just fun, weird things you've made with Ruby. Either the product itself or you use a technique that's very …
Get the full transcript (7,237 words) + summary by email — free
One-time email with the complete transcript and AI summary of this episode. No account needed.
One email, no spam. We’ll also show you what SignalCast does.
You just read a 3-minute summary of a 38-minute episode.
Get The Bike Shed summarized like this every Monday — plus up to 2 more podcasts, free.
Pick Your Podcasts — FreeKeep Reading
More from The Bike Shed
506: The Muppet Software Team
Jul 14 · 38 min
10% Happier with Dan Harris
Longevity Secrets (And Controversies) From The Blue Zones | Dan Buettner
Aug 24
More from The Bike Shed
505: What is a “principal” or “staff” engineer?
Jul 7 · 34 min
Investing for Beginners
AAR57 - What Does Your Perfect Day Cost?
Jul 7
Books, tools, and gear mentioned in this episode
SignalCast may earn commission on purchases via these links.
Tools
“While implementing a type-ahead component in Elm, the type system forced discovery of unhandled UI states.”
- MermaidRecommended
“Prompt an LLM to generate Mermaid diagrams scoped by model and depth — for example, an ERD starting from the User model at depth two, or a call graph tracing a function three levels deep. GitHub natively renders fenced Mermaid blocks in PRs with pan and zoom, making complex changes scannable without prose explanation.”
More from The Bike Shed
We summarize every new episode. Want them in your inbox?
Similar Episodes
Related episodes from other podcasts
10% Happier with Dan Harris
Aug 24
Longevity Secrets (And Controversies) From The Blue Zones | Dan Buettner
Investing for Beginners
Jul 7
AAR57 - What Does Your Perfect Day Cost?
10% Happier with Dan Harris
May 27
Stop Being Hijacked By Anxiety, Grief, and Anger — A Buddhist Approach | Sebene Selassie & Jeff Warren
Latent Space
Feb 27
METR’s Joel Becker on exponential Time Horizon Evals, Threat Models, and the Limits of AI Productivity
Stuff You Should Know
Feb 12
How Lasers Work
Explore Related Topics
This podcast is featured in Best Cybersecurity Podcasts (2026) — ranked and reviewed with AI summaries.
Read this week's AI & Machine Learning Podcast Insights — cross-podcast analysis updated weekly.
You're clearly into The Bike Shed.
Every Monday, we deliver AI summaries of the latest episodes from The Bike Shed and 192+ other podcasts. Free for one show.
Start My Monday DigestNo credit card · Unsubscribe anytime