38: Ep. 38 | Writing for Developers with Piotr Sarna

Brittany Ellich (00:00) Welcome to the Overcommitted Podcast, your weekly dose of real engineering conversations. I’m your host this week, Brittany, joined by…

Bethany (00:07) K and Bethany.

Erika (00:08) I’m Erica.

Brittany Ellich (00:09) The three of us met while working on a team together at GitHub and realized we all are obsessed with getting better at what we do. We decided to start this podcast to share what we’ve learned. We’ll be talking about everything from leveling up your technical skills to navigating your professional development, all with the goal of creating a community where engineers can learn and connect. Today, we are joined by Sarna, joining us from Poland.

One of the authors of the book writing for developers and that is what we are going to talk about today. I’m so excited about it. Thank you so much for joining us.

Piotr Sarna (00:32) Thank

Thanks and hi. so my name is Piotr, but feel free to call me Sarna, because that’s way easier to pronounce for everyone. I programed Distributed Systems for a living, but I also got into writing first blog posts and then books, so here I am.

Brittany Ellich (00:52) That’s awesome. To kick us off, what is one thing you’re currently building or obsessed with learning right now?

Piotr Sarna (00:58) I keep coming back to learning that… what would be the name of it? Like logic gates and stuff, so VHDL and Verilog, so the roots of how all those systems actually work, so every…

year or so I come back to learning all the fundamentals and I hope that in a few months maybe I’ll learn enough to just order my own system on jib like the first one so this is totally unrelated to my day job but something I’m kind of passionate about

Brittany Ellich (01:31) awesome. Doing things that are completely unrelated to my day job is one of my favorite things to learn about as well. Sometimes that’s nice. So we also, there was a co-author for the book Writing for Developers, Cynthia Dunlop, who was not able to join us. She got impacted by the post-AWS flu that seems like it went around to everybody that went to reinvent.

But know you both co-authored the book together. I’m curious how did you two meet and decide to tackle this project together?

Piotr Sarna (01:55) Thank

We actually didn’t meet in person ever, so that’s a fun fact. I’ve only seen Sinfia mostly through Riverside, of course, places. But we worked at ScyllaDB for a time and the story started with a previous book of ours, which was about databases. And the way it started was as follows. I was approached by…

APRES, the publisher, they wanted to actually, they wanted to find an author to write a book specifically about ScyllaDB I kind of didn’t want to do it, so I forwarded them to the marketing department of ScyllaDB and…

we figured out that maybe I will first of all co-author a book with four people total and then make it a general book about databases because a book about ScyllaDB will be out of date the moment it’s released and maybe if we just cover some fundamentals of performance and other aspects of databases it will have better shelf life let’s say and that was a nice

Well, I would call it a success. The book is open source and available for free online. It has quite a few views. yeah, I was happy to see it getting popular enough in our niche. And then, by about this time, I was already kind of hooked on writing books. And when Cynthia approached me about writing another one, I just…

grid on the spot and this time we approached a few publishers. Ultimately we decided on money and yeah, we wrote this one. It was totally unrelated to the previous database one, but it was, I think it was even funnier to write.

Brittany Ellich (03:32) Yeah, somewhat related in the developer realm, but very different topic for sure.

Piotr Sarna (03:37) Yeah.

Brittany Ellich (03:37) Writing a book seems like it’s probably really hard. And then co-writing is probably another whole layer of extra things on top of that. What was the collaboration process like writing a book with another person?

Piotr Sarna (03:48) I’d like to strongly disagree that co-altering is harder, it’s actually way easier. If you co-alter with Cynthia, that’s the secret sauce. Cynthia is first of all a skilled ghostwriter and also a writer, so she kind of took all the burden of pre-editing everything off me. I could just spill out…

barely coherent sentences and she would just form them into beautiful English sentences that we can then pass to the publisher for review.

So it’s way easier first of all because of that and second of all writing a book like a whole book might be a little tough because it might take a year or three. If you write one fourth of a book it’s a couple of months so it’s like you can see the end of it so it’s actually especially with the first database book we actually everyone was responsible for a few chapters.

So all I had to do was write three chapters, if I remember correctly, maybe four, and each chapter is kind of like an extended blog post. So just that, and then you have a book. So I would say that co-authoring is substantially easier for a start, especially, to the point that I would never actually self-author without the co-author and without the synth specifically, I suppose.

Brittany Ellich (05:12) Yeah, that makes sense. I feel like maybe it’s also one of those things where like the idea of writing a book seems very intimidating because it’s a whole a whole book. But does it feel a little bit less intimidating now that you’ve done a couple of them?

Piotr Sarna (05:25) It would still feel a little bit intimidating for me to read the whole book, but yeah, I mean, half? Not so much, yeah. It would just be yet another book. And if you think of every single chapter as an extended blog post, it’s… yeah. You probably already wrote enough of those to comprise for a whole book. So you just do it in a row and then get everything reviewed and published.

Brittany Ellich (05:48) That makes sense. I like the idea of looking at it as an extended blog post. That does seem a lot less terrifying than writing a book. And if I understand correctly, you both write that blog as well. Can you tell me a little bit about what that is and what it’s all about?

Piotr Sarna (06:03) Yeah,

it started as a promo for the book itself. We wanted to have a place where we would continue giving examples of the patterns of blog posts that we described in the book that are up to date monthly. the book is structured in a way that a huge part of it is a couple of patterns that we…

that we just kept seeing everywhere. you browse Hacker News, I can pretty much assign patterns as I see them right now, because it’s like muscle memory at this point. since we already, for every one of those pattern chapters, we had some examples, but those…

would eventually get out of date and we wanted something that is up to date all the time so we just started this monthly this section of blog posts and we just post them there. That’s pretty much it, it’s like a natural continuation of the book.

Brittany Ellich (06:56) Nice. Is there anything that you’ve learned since the book was written from that write that blog? Like, is there any like new insights you’ve gained that didn’t make it into the book since you’ve been running that?

Piotr Sarna (07:07) I think there’s one pattern that we didn’t capture well, which is somebody describing how something totally unrelated to their work works. So it’s usually…

I do assign it a pattern, because we only have so many of them to pick from, but I’m usually undecided about this one, so maybe I consider adding an appendix to the book describing one more of those. But otherwise, no, it’s really amazing how the initial list of patterns applies to any new blocks that…

happen every month.

Bethany (07:41) That’s really awesome. I love that you all are continuing on with your thesis of the book and continuing to provide examples for folks to look towards. So that’s really cool. Shifting into maybe the book specifically. So as we know, the book is called Writing for Developers. And I’m curious from your experience, what gap were you trying to fill in the existing landscape for writing resources? Was it just lacking

Piotr Sarna (07:55) Mm-hmm.

Bethany (08:07) in general or was it lacking specifically for developers? What are your thoughts on that?

Piotr Sarna (08:12) So before our book course release we did some research if there’s anything that already covered exactly the same topic and unfortunately 99 % of books that talk about writing for developers just mentioned documentation which is boring from the start and we specifically didn’t want to describe how to write engaging documentation because it’s a

and instead we wanted to ⁓ share how to

how we think engaging blog posts can be written. And there was just, to the best of our knowledge, there wasn’t a thing that described it specifically for technical people because technical blog posts are, they share some things with…

good writing in general, they also have some specific things that there should be an educational model.

aspect to them which isn’t really necessary for pros. But on the other hand there are some things from writing good pros that also apply to blog posts. So yeah, we just wanted to fill the niche because as far as we know there are lots of very nice blog posts out there so we can learn by example but nobody to the best of our knowledge at least combined them in a book.

Bethany (09:25) definitely makes sense. I was really struck by the concept of the book because I feel like it’s such a fresh take on writing for developers and it’s something that I feel like I’ve been trying to hone in on for a while with this element of storytelling for developers, like being able to craft a narrative but focusing on technology as well. So that’s really cool. I’m curious, for those developers who maybe

Think, ⁓ I’m just writing documentation and I don’t know if this book is for me. How would you respond to that? Are there any concrete ways that devs can apply what’s in the book to their day to day, even if they might not blog or is this really pushing towards the blogging use case?

Piotr Sarna (10:04) We have a whole ⁓ section of the first chapter which is called Why Write? So it’s probably an extended answer to this question and it also covers a huge list of excuses why not to write one of it is kind of could be summarized as I only write documentation. Well, documentation is usually…

about something potentially interesting that was implemented before, so you can also twist it into an interesting blog post instead of just talking about the details. And this is just one of those excuses. There’s a whole list and we dealt with each one in one of the first chapters. I think it was even chapter one, just to get everybody started.

Bethany (10:47) Man, definitely mind reading. That is really cool that ⁓ you all tackled that already. I’m excited to dive in and read more about that. Something that you also might mention in the first part of your book, but is there three things that you’re hoping that folks take away from this book? Or if they were to only remember three things, they remember XYZ. Is there anything about this book or is it just generally?

supposed to be a reference or what are your thoughts on that?

Piotr Sarna (11:15) So I think since I came up with three characteristics of a post that everybody should remember, so I can just quote that. It was an intriguing topic, distinctive educational core and smooth delivery. And they are all described in the book. But it is a good resource, even if you just want to look at a few examples to get you started. And because usually it’s easier if you see a…

blocks structured in a similar way that you would like something expressed or maybe you just like the style of someone and you want to publish something in similar style then going through the examples and seeing what were the good parts of some specific blocks and what have been improved might just inspire you as well.

Bethany (11:54) Very cool. I’m excited because I made sure to get the physical copy to annotate a lot with this book because I feel like there’s going to be a lot of takeaways from it. So very, very exciting. Is there any piece of writing either from you or someone else that you think every developer should read? Just like a good example of what developer writing looks like.

Piotr Sarna (12:16) It might be a little unfair to list just one, because we tried to pick those examples per pattern and they are all something that we consider really good. The one that I will keep remembering forever was one from Tiger Beetle database, because they went ahead and implemented a game.

which run in browser just to make their blog post cooler, which worked obviously. So yeah, that’s the kind of initiative I would always support. And it was also very educational and technical and so on. So then that’s something I definitely remember, but all of the examples are quite distinctive and very nice.

Erika (12:56) So we are actually kicking off a book club for writing for developers with the overcommitted community. And we learned a lot from our first book club. And we’re going a little faster this time. We’re reading two chapters a week and using multiple platforms. We’re using Discord and Blue Sky. And we’re also doing some sync meetings, video calls.

Piotr Sarna (13:16) Mm-hmm.

Erika (13:16) try to make it more accessible for people with different schedules and communication preferences. So have you been a part of any book clubs in the past, remote book clubs that have done things really well that we can maybe steal from?

Piotr Sarna (13:30) We were featured in Phil Eaton’s book club with the same book, although that one was mostly an email list discussion.

On the one hand it was quite easy to take part in because you just reply to an email but then yeah there weren’t as far as I know there weren’t anything sync meetings or anything like it so there’s not much to share because that one that one was text only

Erika (13:55) Well, yeah, we’re really excited to have those live discussions and sort of have both the opportunity to participate through writing, which is good practice, practicing what we learn and also the discussions to involve people.

Piotr Sarna (14:13) Well, if you would like

to make this particular club more practical, then you can just gently force people to also try writing something along with the book. And just publish it, because it doesn’t take much to just publish something. Worst case, nobody notices it, but it happens to every other blog post.

Erika (14:23) Yeah.

Well, that’s good. Good advice to keep in mind for anyone who might be participating and learning. For anyone who’s starting the book, what would you suggest as sort of a mindset of going in? yeah.

Piotr Sarna (14:47) You could copy the author’s mindset. So first one was that we wrote this book totally out of order. don’t feel inclined to read from chapter… I mean, starting from chapter one is probably a good idea. We did write that one first, but then it was…

really a random choice of what we felt like writing. So readers are encouraged to just read what they feel like reading. So in particular, there is no order of patterns that you need to read at all. But also if you would like to just read the intro and then skip straight to patterns because you can’t resist just seeing what they are, just go ahead and then you can catch up on all the other advice that is in the book.

They’re a bit too stripped with the order. Every chapter with patterns has a few blog post examples and there are also links to them. If you own a paperback copy then you also have a repository that has all the links so you can just follow and actually see them because we couldn’t reliably, for instance, include this web browser game inside a paper book.

just need to go ahead and see it yourself.

Erika (15:55) We’ll include that in the show notes as well with a link to the book. And that’s good to know about the book being not necessarily in a strict order. And it sounds like it’s really centered around these patterns, the sort of content patterns that you identified. So that’s a good place to start and focus if people are looking to focus on one area.

Awesome. So beyond individual skill building or personal brand building, what role do you see writing culture playing in engineering teams and organizations? Presumably a lot of our listeners are working developers, so they’re looking to apply.

this content to their work. So how do you see that applying to day-to-day and how can developers advocate for good writing practices on their teams?

Piotr Sarna (16:48) So I was fortunate enough to join CWB, which already had a very healthy writing culture. It was maybe a little too healthy, because I was kind of forced to write, but I grew to enjoy it. Like, really enjoy it, not Stockholm Syndrome. Enjoy it.

And it does make the whole engineering culture so quite healthy because if everyone keeps writing technical blog posts that are…

that are just published for everyone to read, then it’s first of all clear that you also understand what you implemented, which is quite important.

And then those blog posts usually serve for a better way of actually documenting the interesting parts of what happens inside the company. Because nobody reads documentation end to end. if there’s a nice interesting blog post with some surprising conclusions, then everybody would actually write it. Those posts actually also lure people in, because if a company has an engaging blog,

there are some corporations that have very good technical blogs like Cloudflare or Netflix or others and they just make people want to join the team that also writes those kinds of posts and as for starting the culture if it isn’t there

I think it’s worth trying just to first of all write something upfront and then start asking around if it could get published officially as a company blog because there isn’t usually a reason to say no unless there are some trade secrets in the blog post which you should just remove. But otherwise it’s probably best to just write something then ask and worst case you can just publish it on your personal blog if it doesn’t work out.

Brittany Ellich (18:32) I feel like, especially in so many companies that are mostly remote, like GitHub or like, you know, a of companies now, writing is really the one thing that is surfaced, you know, like across different teams. And it’s one thing, like if you’re like trying to improve visibility in the organization, it’s like very, very important, I feel like, to be able to write and write well and tell a narrative that other people can pick up. So it’s definitely, I think, one of the best skills for developers to invest in.

Piotr Sarna (18:43) Mm-hmm.

Brittany Ellich (18:59) In my opinion. excellent. This has been great. And I’m so excited to kick off the book club. think we were going to start with chapters one and two when this, by the time this episode kicks off and we’re going to have a, we have a discord community already that folks can join if they’re interested in being in it. where we’ll have some synchronous discussions like Erica said, and then we’ll also, you know, just have a space, not only to talk about the book.

But to share your writing, if you’re listening and you’re like, hey, I wrote a thing and I want other people to see it, that that’s a great spot to do that. So we always wrap up our podcast with a fun segment. And this one, I don’t know if it’s actually going to be that fun or not, but this is what I came up with. We’ll do a round robin so we all get to, you know, admit a little bit of something here. But the question I came up with was what’s the most cringe worthy piece of writing you’ve

produced in your career, something that makes you like look back and laugh at now. I feel like this could also just be like code you’ve written because I feel like that is very something that a lot of developers can identify with. It doesn’t necessarily have to be writing. I feel like anything that I’ve written beyond the last like three weeks is usually something I’m like, who wrote that? it’s me, great. So I’ll start and we’ll go around.

I think that one of the most cringe-worthy things, blog posts that I’ve written is I have one blog post that I keep around just as like a lesson learned where it was when I first learned about AI and I was like, ⁓ man, I’m going to copy this thing into chat GPT and see what it says. And it produced something from like what I had written that I was like, man, this is very obviously AI generated and not great, but I’m going to save it because I think it’s hilarious and nobody’s going to read that.

And now it’s on my blog, but ⁓ it’s the Boise Code Camp 2024 post. It is very clearly a lot of AI flowery content that I’ll share. It’s, yeah, I feel like there’s a learning curve with AI things where people are like, I’m gonna do everything with it. And like, okay, no, nevermind. I can do some things with it.

The only very cringe-worthy piece of it is it had really good SEOs. When I looked at Boise Code Camp last year, I was like, ⁓ it’s on the front page of Google for that, which is when I was like, man, that’s not great. But yeah, that is mine. Bethany, would you like to go next?

Bethany (21:16) Yeah, so how many dashes were in that? In lists of three. Just a string of ⁓ dashes. That’s funny. Yeah, I was having trouble thinking about this because I’m like, I probably haven’t posted anything that I thought was cringe, but my mind went to anything I’ve ever tweeted or posted on Blue Sky. I just feel it’s automatically cringe. I am terrible with short form content or distilling my thoughts into… ⁓

Brittany Ellich (21:19) It’s probably all dashes, like the whole thing. Yeah.

Bethany (21:43) a short set of characters, so I’ve definitely posted some cringy things and just, like, deleted it immediately because I was like, what am I saying? I think recently I posted on Blue Sky, I was like, I don’t trust something that’s marketed as viral, and then I’m like, what am I saying? This is the most lukewarm take ever, so I instantly deleted it. But that was…

That was the biggest thing I could think of. I don’t have a blog so I haven’t had any experience with that, but maybe with this book club I’ll finally get around to doing that, as that has been a goal of mine for a while. So, very excited to have a blog and hopefully not post-cringey things. So, Erica, why don’t you go?

Brittany Ellich (22:12) yet.

Erika (22:23) Yeah, I also think that I have not written externally enough. I write a fair amount like internal to GitHub, but I feel like I like pre-edit anything external with the cringe factor. I did like post, I think like when I did my boot camp, we all had to do some kind of like blog post about our final project or something and like I guess I would say that, but I don’t think it’s bad.

I think part of this is like we’re constantly learning and like when you look back and you’re like well that that’s so obvious like Why would like why would anyone write a blog post about that because it’s like HTML and CSS like who cares? but I think yeah like part of learning how to write is kind of like getting over that hump and

being kind with yourself of like, it’s okay, that was past me and you know, I don’t have to know everything to have something worth reading and you know, I learned it at some point so maybe somebody else needs to learn it too. Yeah.

Brittany Ellich (23:26) Sarna, did you want to share anything, if you have anything that you want to admit?

Piotr Sarna (23:26) Yeah,

sure. The most cringe-worthy by far would be my bachelor’s thesis, but that’s not probably publicly available. Hopefully isn’t. But one actually public one, one is cringe on purpose. The first chapters to the database book were written by me and they were short stories of database performance with…

purposefully very forced humor that wasn’t very funny and I actually had a hard time actually reading this because it’s just sad but this is also the that reportedly inspired Synthea to reach out to me to write another book so I guess it’s good that I did and as for AI generated content we also tackle it in the book

because our main advice is to by all means use AI to revise and review your blog post but do not let it actually create content. We also provide some examples of this generated content which is especially I think it was generated over a year ago so

The models did get a little better with writing, although not that much, but some of those examples were very, very hard to read, especially if AI tried humor. Again, it just can’t do this at all.

Brittany Ellich (24:47) Yeah, I’m willing to be an example of poorly, poorly revised with AI things. Yeah, I can definitely overdo it. And I think it’s a really great editing tool. At least as like a first pass before, you know, to point things out. But I’ve learned like, oh, okay, I don’t really like it actually making changes. I just like it to suggest changes to me and not actually make changes to the thing that I write because the changes it makes kind of suck.

Yeah, cool. Well, that was fun and a little bit therapeutic as well at the same time. So thank you all for participating. With that, we’re going to wrap up. ⁓ Thank you so much for joining us. If folks want to find you on the internet, where is a good spot to find you?

Piotr Sarna (25:28) You could start with this repository for a book and you could probably find me through there or I can just leave my contact info somewhere so you can post it. I’m technically also on Discord but I’m a Discord boomer and I just can’t use it. It overruns me with these flashy images and notifications so I’ll probably miss whatever…

people approach me within that particular platform. yeah, email is fine.

Brittany Ellich (25:56) Awesome. Yes, I love the term Discord Boomer. That’s, that is great. Excellent. Well, with that, thank you so much for tuning in to Overcommitted. If you like what you hear, please do follow, subscribe, or do whatever it is you’re supposed to do on the podcast app of your choice. Check us out on Blue Sky. Join us for Discord, particularly as this book club kicks off, and share with your friends. Until next week. Goodbye.