Ep. 23 | Mastering Storytelling in Tech  ## Metadata - Author: [[Overcommitted]] - Full Title: Ep. 23 | Mastering Storytelling in Tech - Category: #podcasts - URL: https://share.snipd.com/episode/60a5ccf9-44e3-4cee-a76d-2a322b2a9e2a ## Document Notes ## Highlights - **Visuals And Narrative Boost Documentation** - Visual design and a clear arc make technical docs feel like a journey rather than a wall of text. - Emotional levity (icons, gifs, illustrations) increases engagement and retention. Transcript: Erika First thing that comes to mind for me is visual storytelling. I've seen some documentation, the Astro documentation comes to mind, where it's like very visually appealing and a little like going back to the gamification episode where like it's Like it's very leveled like you you can see progress as you go through the documentation it's sort of a challenge um and so the story the story is like you know your understanding of this Information so i think in a world online where so much is visual, like really having that like nice, nice looking visuals, icons, people use emojis and gifs a lot, which is helpful in Kind of bringing some levity. And then, yeah, like having having an arc of sort of like beginning, middle and end of where you're trying to go. I've also found to be more engaging than the flat wall of text. ([Time 0:01:05](https://share.snipd.com/snip/87278598-50c1-430f-9b3c-38850aeba2cb)) - **Design Docs For Newcomers First** - Make docs approachable by avoiding jargon and targeting first-time readers on the front page. - Assume readers will jump to "getting started" and design that experience for newcomers. Transcript: Brittany Ellich Very, very hard to get through. I think the other thing that sticks out to me is approachability. I can't tell you how many things, especially early in my career, that I started reading like the front page of the docs and they would start going into how like this is an expressive language That uses, you know, that's I can't even think of all of the different words now, but like there's a lot of terms that we use within software development that are just not approachable At all to folks that are very, very new. And those are probably the ones that are going to be reading the front page of your docs anyway. Most developers are going to just jump to the getting started in the like NPM start part anyway. So making sure that it's something that's approachable and keeping your audience in mind, I feel like is really important. ([Time 0:02:20](https://share.snipd.com/snip/bbb3ae4d-b310-4c25-8bff-4ff88388b631)) - **Open With Why People Should Care** - Always answer "why do I care?" early: explain the problem you're solving and why someone would choose your solution. - A strong hook and clear benefit are essential for presentations and docs alike. Transcript: Erika Yeah, I think the other thing that I find missing more often than not is a question to the answer, why do I care? Like any software you're building is meant to solve a problem. But like, I can't count the number of times I've gone to a site or documentation for a piece of software. And they assume that you already know what problem you're trying to solve by coming to this solution. It's like, no, no, you need to tell me, like, why would I choose this over something else? And like, what specifically is the problem that I'm addressing here? I completely agree. And I've been thinking about this a lot from a not just documentation perspective, presentation perspective. Bethany Janos I'm preparing for lightning talk at GopherCon next week. It's part of the lightning talk. So it's just a big segment of talks that people are listening to. So I've got to kind of sell why people should care about what I'm talking about, capture their attention. ([Time 0:03:04](https://share.snipd.com/snip/30fc3fe3-86e1-404d-805e-6063c0eccda9)) - **NeoVim Lightning Talk Prep** - Bethany is preparing a lightning talk titled "Not Your Parent's Editor, A Gopher's Guide to NeoVim" for GopherCon. - She plans to use self-deprecation to hook the audience and reframe Vim as modern and approachable. Transcript: Bethany Janos From a not just documentation perspective, presentation perspective. I'm preparing for lightning talk at GopherCon next week. It's part of the lightning talk. So it's just a big segment of talks that people are listening to. So I've got to kind of sell why people should care about what I'm talking about, capture their attention. And I think there's not that many examples of just how to do that effectively, you know? And I think with presentations at work or like at a meetup, that's also important. So many work presentations, I honestly just like zone out because it's totally not meeting me where I am. It's not explaining or conveying topics or in a way that a lot of the audience can understand. So it's just like, whoosh. Erika But that's how you get your... Oh, I was gonna say, side note, what are you talking about? Bethany Janos I'm so glad you asked. Hi, my talk is called Not Your Parent's Editor, A Gopher's Guide to NeoFem. That is so you. Yes, I'm so excited. I love being able to talk about tooling and stuff. So this is my dream. And I think I applied for it for a regular talk, but I think the lightning talk is a lot better of a format for this because it's kind of like a short and sweet thing. And I can kind of maybe take people by surprise. But I'm ([Time 0:03:40](https://share.snipd.com/snip/1f9391e4-028f-4aac-a040-7a11c631b957)) - **Start Talks With A Hook, Then Introduce Yourself** - Lead with a nontraditional hook (visuals or scenario) before introducing yourself to keep attention in short talks. - Use visuals early and then transition to identity and content to avoid losing listeners. Transcript: Brittany Ellich I know you said that you're starting with some self-deprecation, which is a classic. But I think that also gives up a really good point about what's important to storytelling and especially for tech presentations that I've seen. Having a good hook, I feel like is really important at the beginning, especially for a lightning talk. When somebody's sitting there listening to more and more, a bunch of lightning talks over and over, having a hook that's not just, hi, my name is Bethany. And this is the thing that I am presenting is super important. One thing that I've been doing that I feel like has been really helpful for me is like, I just jump immediately into like some visualizations and talking about a thing using some of like The illustrations and stuff that I do. And then like a few minutes in, then I'm like, hi, I'm Brittany. I'm talking to you about this and then move on. Bethany Janos Yeah. You did that in your, uh, your gopher con presentation. I love that. That was great. Yeah. Brittany Ellich I got a lot of good feedback about that. ([Time 0:07:06](https://share.snipd.com/snip/85a5c9d6-362b-42db-b164-511570f4941a)) - **Emotion Makes Technical Stories Memorable** - Emotional connection helps technical storytelling stick, but avoid manipulative tactics. - Different mediums require different balances between emotion and information. Transcript: Erika Good stuff yeah and i think an important element there that you kind of touched on is like the emotional side which feels completely divergent from technical speeches or technical Talks and i think like we don't always reach for that because like well why is it important like why is it important how this makes me feel or you know um yeah but like we're humans like we Do need some of that some of that consideration so not unlike a you know like I think it can be to like a degree where it can be manipulative. So like, don't go that far. But like, you know, a little, a little bit can can go a long way, I think. Bethany Janos Yeah. And I think it does go the other direction, though. Like we were talking about documentation. In your documentation, people are probably looking for a specific thing. And you should know, or like, at least understand what that is it's likely not emotional connection if they're looking at technical documentations you've got a either if you're an Open source package tell people on why they even want this what what does it do like what are its benefits and like rattle this off and if it's people searching for documentation making Sure that's like front and center and available and easy to get access. But it's interesting how the medium really affects like what you're going for. ([Time 0:09:50](https://share.snipd.com/snip/38570f5e-9229-4a49-b803-0b844910f4c8)) - **Julia Evans' Zines As Teaching Models** - Erika praises Julia Evans' wizard zines as exemplars of making complex topics stick with drawings and narratives. - Those zines help readers visualize commands and remember concepts long-term. Transcript: Erika Yeah, I think the difference could be that like not all stories need to convey like information. Like technical stories are different from other stories, like purely like emotional or like, you know, something like literature, book, whatever, like and that like you don't need To get any information from like a story that is there for your enjoyment like but technical stories do need to like convey information and you don't want to dumb it down um because of The way that you're presenting it like i feel like that's if there's, like, a reason why people, like, wouldn't use storytelling for these kinds of situations, it's because, like, Yeah, like, they want to present the information, like, in its purest form. But, like, I don't necessarily think it's a trade-off you have to make. Like, think of Julia Evans and, like, all her, like, wizard zines and stuff. It's like I learned so much from those like those cartoons like I visualize her git zine every time I do any git command it's like that is like that is exactly like the point for me is like No actually like the story makes it stick better um but it's also like you know I also remember like I mean yeah no secret that I was a musician and like basically the way I studied for any Test in high school was like turning into a song like AP history the only things I remember to this day are like things that were set to songs or like my whole SHE vocabulary like the only Way I remembered any of those was because of like being set to a song so you know is it like every song is an educational like test study song no is every story a technical story no but like It can yeah I can help make it stick help it make it more engaging um and it it's the same information so yeah I think as long as you keep that as long as you keep the um what is it like quality Of information, yeah, you can have both. Brittany Ellich Erica, I would love to hear you make some songs about these technical concepts so that I can finally remember how to properly rebase my commits. Please. Yes, please. Erika Actually, this is a great challenge. Like, as we're talking about, like, you doing your drawings and stuff, like, yeah, this could be something I could bring to the world. Please, please do. That would be amazing. The wizard scenes music. Yes, please. I can get Isabel to do some backup vocals here pretty soon. Bethany Janos Yay. Erika That's amazing. I love all these analogies. I mean, wizard scenes is such a ([Time 0:12:45](https://share.snipd.com/snip/fcfe031b-c42b-4fb5-a4cc-2ce2fb284f4f)) - **Respect Audience Attention** - Treat audience attention as a gift and craft a space people want to be part of by being inclusive and respectful. - Shift mindset from "I must transmit" to "I invite participation" to improve engagement and enjoyment. Transcript: Brittany Ellich Thing that I think here is if I'm presenting something that I know is going to be presented to like VPs or like executives or something at that level, typically you want to have something That's a lot more succinct and to the point and, you know, a single paragraph or a one pager that just kind of gets to the point and doesn't have a lot of extra fluff and storytelling compared To, you know, if I'm presenting something that I'm going to put on my blog or that I'm going to, you know, present in front of, you know, a wider audience than I think about, you know, trying To add more to it to make it more memorable. Erika Yeah, I think something I've been trying to do more recently is like adopt some of this mindset of like the audience is like gifting you their time and attention and like being very conscious Of like making your space that you're creating a space that they want to be a part of. So like I don't think it's dependent on like, who's in your audience, but like, adopting that mindset that like, like you want them to be there. Yeah, like, I think sometimes in the past, like, I've been like, oh, I have to, like, I have to get this information across. And like, you know, it's a challenge or like, you know, like, they're gonna think worse of me or have sort of like a negative mindset. And I've been trying to like, adopt more of a, yeah, positive, like inclusive mindset with like anyone that I'm talking to in a group. ([Time 0:16:30](https://share.snipd.com/snip/981a3c80-3f55-49fa-929d-ef2f5f3b6fce)) - **Use AI, Then Add Human Judgment** - Use AI to synthesize and assist, but always edit outputs to match your voice and respect readers' time. - Avoid sending unedited AI-generated content that wastes others' attention. Transcript: Brittany Ellich Across, but it's made presenting a more enjoyable experience for me. I think that's something that is kind of related to that too, that I've been thinking about a lot recently is I feel like I went through this curve of using AI for things like writing and Telling these stories more like I used it a ton. I was like, this is such a cool tool. And now I'm using it less because I don't know if it's just me, but I feel like if I present a bunch of stuff that is only written by AI, it doesn't necessarily respect like people's time As much as if it's like written by a human. Like if you just say, take these bullet points and make it a story to chat GPT and you don't even take the time necessarily to like read through it and like know that it is like, you know, Your own voice and something that you want to convey and expect other people to spend their time doing that, then, you know, that seems, I don't know, kind of disrespectful of people's Time as well. I don't know why that came to mind while you said that. But yeah, taking, you know, appreciating the fact that you get people's attention and not trying to like hog it with things that are like not actually important or interesting or something That you would spend the time working on. Bethany Janos I love that so much. And it reminded me of an article that I was chatting with a friend the other day. She mentioned, and it was saying, sending AI slop is an act of war because you're almost wasting people's time with a lot of it. I think AI is an incredible tool for synthesizing things, searching, understanding things in a voice that makes sense to you. But when information is pushed to you and it's AI, it does feel like a waste of time because, Brittany, to your point, people aren't spending the time to necessarily make sure it's good Or make sure it conveys what they actually want it to. It reminds me, there was this ad for Apple doing something like Apple's AI or whatever. And somebody took bullet points. It said, make this a long email. And I made it a long email. They sent the email. The person on the receiving side took that email, summarized it into bullet points. It's like, what are we doing? We just killed like five trees with that. Not that many. ([Time 0:18:00](https://share.snipd.com/snip/34d5520a-24fe-42e0-9771-381fed7117d8)) - **Human Element Is Irreplaceable** - No matter how capable AI becomes, the human element in storytelling remains irreplaceable. - Human empathy and voice are essential for meaningful technical communication. Transcript: Erika A funny illustration i think to like take it back to to this idea of like audience too like i think in that example it's like on either end it's like you are perceiving what you think the Other person wants sending this as a like paragraph format versus bullet points but what they actually want is bullet points um so like in those like working relationships too like I don't know like it maybe is worth like i don't think about this that often but it is maybe worth like spending time with people that you work with more frequently to like figure out what The best way to communicate with them is like similar to how people are like I'm gonna customize my you know GPT interface to or like chat interface to like speak in the voice that I wanted To like I'm gonna give it like Southern California colloquialisms or whatever like I don't know like that's whatever to me but like I don't think I've thought of that with like my colleagues. Like, I think I typically think of like, how would I want to receive this information instead of, oh, what would make the most sense to them? Yeah, absolutely. Bethany Janos It is interesting how as we go forward with this age of AI and stuff, how it's becoming more and more clear. What is the value that we're adding here? What is AI over and versus what do we still have concrete value in providing and i think it definitely becomes more and more clear as we go on um and probably will continue to as a ai gets Better or how we like reimagine what things what work looks like past this but i'm sure we've talked about that ad nauseam in other episodes well and to like i't know, not go too far down Erika This, but like to make this point, it's like AI, as good as it will be, will never replace that human element. Period. 100%. Yes. ([Time 0:20:28](https://share.snipd.com/snip/d41178c2-37f0-4cec-808c-429159f05cfb)) - **Docs As Personal Brand In Remote Work** - Remote work means your docs and PRs often become your personal brand and primary interaction with colleagues. - Thoughtful written stories and respectful tone shape perceptions in distributed teams. Transcript: Brittany Ellich So I feel like another aspect of that storytelling really is kind of like to speak to other things we've talked about in the past is like the personal brand or whatever of you are you might Just be your documentation um for other co-workers because you don't necessarily get a chance to just hang out in you know an informal way um i feel like taking time to you know consider Your audience and then also to make sure that what you put out there is you know is good storytelling or is it like it's a good you know conveyance of what you know and what you want to share Erika With other people is is very important too it's true though actually i think that's another like vector of communication that we've like briefly touched on but like maybe to like draw The line of like virtual versus in person being a factor in how you communicate um there's like a whole book that i was hearing about that's uh like how to communicate in a virtual setting Like what kinds of meetings to have you know like how to craft your messages like whether to use video or not, like all these things that are present in a virtual working environment that Aren't in person. So like, yeah, I mean, not to like overthink everything. Like I think, you know, it's, yeah, it's not rocket science necessarily, but to be conscious of that too. Like, you know, when, when there's a screen in front of you, like you might I think I think my tendency is like when there's yeah, like when I'm behind a video or something like I have to Like amplify my emotions when I'm speaking because it's like there's an element of distance there. So if I want my emotions to come across, I have to be that much more expressive in my voice and my face. Yeah. And same with like written communication. Like I have to be like, I'll use even more imagery, like emojis, gifs to make it exciting. Bethany Janos And also like, yeah, you have the opportunity to like make it really clear and concise. Absolutely. I love that the GitHub onboarding mentioned using emojis a lot and written communication to convey like what your tone is. And that's such a good point too, that over a video, you can see facial expressions and hear vocal inflections, but it's not quite the same as being in person. And you do have to amplify it. I think that's why Zooms end up being a lot more exhausting than just regular having meetings. But that's such a real thing. I think also the book we're reading for our book club looks good to me. It mentions this with PR feedback as well and making sure that your tone is good for giving feedback and something that can be very vulnerable for somebody is putting their code out there For review or vulnerable for you to ask a question about it so making sure that your tone is not accusatory if it's saying hey what's what's happening here what are we doing here and then Also using different language like we or the pr rather than why did you do this? Why did you choose to do this so that you're not like putting the person on the line? So I think those kinds of things are so important. ([Time 0:22:37](https://share.snipd.com/snip/b0c4ee1a-0193-4b82-9a5b-12633eb2711f)) - **Write PRs Like A Story** - Treat PRs as storytelling opportunities: explain the why, how, and expected post-deploy behavior in the description. - Use clear beginning, middle, and end to make code changes discoverable and reviewable. Transcript: Erika First and communication gets even more important. She even describes the pr as the opportunity to tell a story um and yeah she mentions like the pr description as an opportunity to do that like labels you're like yeah the title of your Pr like every every element of it of like yeah your code obviously like every element can be part of telling that story. And going back to the beginning, like of like what you're trying to solve, like, yeah, what's the beginning, middle and end? Like, why are you doing this? How are you doing it? And what's it going to look like when it gets deployed? ([Time 0:26:00](https://share.snipd.com/snip/51af7ab4-17dc-46b7-80ab-a5745106a8cd)) - **Make Content Scannable And Glossary-Ready** - Make documentation scannable with TL;DRs, headings, bolding, and persona-focused sections for fast discovery. - Include a glossary in slides for mixed audiences to ramp up terminology quickly. Transcript: Bethany Janos I will read something out loud and see if it makes sense. Erika That's a pretty low, low lift way of finding out if it reads like a story. Brittany Ellich When I actually just was writing something earlier today, and one thing that I like to do is try to read it from different perspectives, like put myself in the shoes of like, all right, What does this look like if I'm somebody on the team that didn't work on this? Or what does this look like if I'm somebody on a different team that has no context of like what this team is working on to see like, what does this release mean to me? Like, is this actually important? So one thing that I usually like to do is to have a section that just says like, why is this important? And use a lot of headings and bold and like bullet points to like make it really easy to scan um and probably make it look like it was written by chat gpt but like i think there are a lot of styles From that that i've sort of adopted especially since we use markdown a lot at work for for writing discussion posts and all that where like i try to make it easy to find the information Based on different personas of who might be reading it so having like a tldr at top, if you just want like a summary of it or have a section that's why is this important to, you know, our customers? Why is this important to my team? So make it easy to go find because I think a lot of times people don't read, you know, documentation top to bottom. They typically look at it to scan it and just get the most important stuff and like figure out what's relevant to them so that's typically what I like to do that makes me think too um of like Erika Accessibility of information and like a lot of the same principles that we use when designing an accessible website also apply to this idea of like discoverability those headings Like yes they're like like yeah headings are like a part of the like accessibility standard like using the appropriate heading for a piece of information um which makes it easier for A screen reader to understand it but it also applies for everybody and to your point anybody reading this information will look for a certain like flow of headings um just like naturally And so like adopting that mindset can help improve the experience for everybody it actually reminds me too that i have a blog post on the github blog from like three months ago with a member Brittany Ellich Of the docs team where he sam browning wrote you know a lot of details about like how to write a good doc. And I wrote about like how to write good documentation as a whole. I'll share it in the show notes. But yeah, making sure that things are easily scannable is pretty key. Bethany Janos Yeah, absolutely. And to that point, I've found success recently with, especially in presentations that are to a larger group that might not have the same understanding of what I'm presenting, adding A glossary to the front of your slides and then sharing out the slides so people can keep it on that side is really awesome for being able to ramp up quick with having the same language or The ubiquitous language for what your presentation needs. And so I've done that a couple of times in our availability review. And this was part of the advice of somebody who was doing availability reviews a lot. And it's been really awesome. And I've gotten a lot of good feedback from that. ([Time 0:29:25](https://share.snipd.com/snip/c98732e6-f580-416c-a229-ba80c57162a3)) - **Mad Libs: Flappy Architecture Meeting** - The hosts played a developer Mad Libs that produced a chaotic "regal architecture review" with a stapler thrown and a "flappy" outcome. - They used the game to illustrate meeting drama and the humor in engineering decisions. Transcript: Bethany Janos So let's do our fun segment. I am actually stoked about this. I had AI create a Mad Libs. So I don't even know what the story is going to be. But it's developer related and we'll fill it out together. So do we want the great incident response, deployment day drama, new developers first day, or architecture decision meeting? Decision meeting? Let's do it. Let's do it. All right. So adjective describing importance. Regal. Okay. A noun, like a system component. A cache. Widget. I like it. I like it. Oh, yeah. Brittany Ellich Let's do that. That was a good one. All right. Bethany Janos A verb discussing action. Computing. Processing. Processing's better. Yeah. Let's do processing. Wish I had Erica's songs for SAT vocabulary and I'd be doing a lot better here. How about a large number? One million. Oh, one million. What about one billion? One billion. Brittany Ellich Yeah. All right. A senior developer name. Brittany. Erika I was trying to think of another. Brittany Ellich What? I was trying to think of something generic, like generic man name, John or something. Bethany Janos Bethany can be the other one. All right. The other name will be John or bethany we'll do we'll do john because he's not here definitely part of this adjective describing disagreement hence i bet you did great on the sat yeah I know i'm so jealous right now actually for listeners who might not know this erica is a star at crossword she does the new york times crossword like nothing else so um how about a technology Framework what's like technology slash framework so we could do like kubernetes or like oh yeah kubernetes all right we'll do that all right a different technology astro yeah okay Like a noun for a meeting room item paper marker stapler all right let's do stapler that's funny verb for a decision making action cited selected by nominated finalized finalized yeah I like that all right an adjective describing outcome succeeded uh no that was successful floppy oh that's amazing do we want floppy or flappy maybe flappy like a flappy monitor okay Finally time period era i love it all right let's generate our tech story all right the team gathered for a regal architecture review meeting to discuss our new widget system we needed To process how to handle 1 billion concurrent users without breaking the bank. Brittany was convinced we should use Kubernetes, while John became tense and insisted that Astro was clearly the superior choice. The debate got so intense that someone threw a stapler across the room. After three hours of- Definitely John. Oh man. Yeah, John is definitely the type to throw a stapler. After three hours of passionate discussion, we finally decided to finalize and go with a hybrid approach that made everyone equally flappy. Fix era later, we realized we should have just used a simple database and called it a day. But hey, at least our documentation is impressive. ([Time 0:32:55](https://share.snipd.com/snip/f34c657a-88f5-4aa0-82b8-be213909e87a))