Developers Should Prioritize Educational Writing for Clarity and Culture

Key Quotes

"We've we actually didn't meet in person ever so that's you know a fun fact we've always only seen uh cynthia mostly through riverside uh of all places we worked at scylladb for a time and the story started with our previous book of ours which was about databases and the way it started was as follows i was approached by uh 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 would 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 could have better shelf life let's say"

Piotr Sarna explains the origin of his first book, "Database Performance at Scale." He describes how the initial idea for a ScyllaDB-specific book evolved into a more general database performance guide due to concerns about its shelf life. This illustrates a strategic decision to broaden the scope for greater long-term relevance.

"I'd like to strongly disagree that that co authoring is harder it's actually way easier if you co author with cynthia that's 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 to beautiful english sentences that we could then pass to the publisher for review so uh 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 in with the first database book we actually everyone was responsible for a few chapters so all i had to do was like write three chapters if i remember correctly maybe four and each chapter is kind of like an extended blog post so we just have and then you have a book so uh i would say that co authoring is substantially easier for a start especially to the point that i would never actually self author without uh without a co author and without cynthia specifically i suppose yeah that makes sense"

Piotr Sarna highlights the benefits of co-authoring, particularly with his co-author Cynthia. He emphasizes that her writing skills significantly eased the editing process, allowing him to focus on content generation. Sarna also suggests that breaking down a book into smaller, manageable parts, akin to extended blog posts, makes the overall task less daunting.

"so before our book or at least 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 and just mention documentation which is boring from the start and we specifically didn't want to describe how to write a book engaging documentation because it's a moron instead we wanted to share how to how we think engaging blog posts can be 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 well there's some uh some things with good writing in general but they also have some specific things like they should be there should be an educational aspect to them and which isn't really necessary for prose but on the other hand there are some things from writing good prose that also apply to blog posts so yeah we just wanted to fill the niche because as far as we knew 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 any book that definitely makes sense"

Piotr Sarna explains the gap in existing resources that led to the creation of "Writing for Developers." He notes that most writing guides for developers focus on documentation, which he finds unengaging. Sarna and his co-author aimed to fill this niche by focusing on how to write compelling blog posts specifically for a technical audience, incorporating both general prose techniques and unique educational aspects.

"well i think sam came up with three characteristics of a post that you should write 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 blog structured in a similar way that you would like something is first or maybe you just like the style of someone and you want to publish something in a similar style then going through the examples and seeing what were the good parts of some specific blogs and what could have improved might just inspire you as well"

Piotr Sarna shares three key characteristics for effective developer blog posts: an intriguing topic, a distinctive educational core, and smooth delivery. He suggests that the book serves as a valuable resource not only for its advice but also for its examples, which can inspire readers by showcasing well-structured and stylistically appealing blog posts. This approach allows readers to learn by observing and adapting successful patterns.

"so i was fortunate enough to join sedly b with 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 stop from syndrome enjoy it and it does make the whole engineering culture also 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've 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 and if there's an and there's a nice interesting blog post with some surprising conclusions that everybody would actually write it those posts actually also will lure people in because if a company has an engaging blog there are some um and corporations that have very good blog very good technical blogs cloud flare 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 we could get published officially as as a company blog because it's 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"

Piotr Sarna discusses the impact of a strong writing culture within engineering teams. He explains that such a culture not only clarifies understanding of implemented work but also serves as a more engaging form of documentation than traditional end-to-end documentation. Furthermore, Sarna suggests that an active company blog can attract talent by