Writing for Developers  ## Metadata - Author: [[Nicolas Fränkel]] - Full Title: Writing for Developers - Category: #articles - Document Note: --- tags: - #technicalwriting - #developeradvocacy - #open-source Author: Nicolas Fränkel Source: Writing for Developers review, blog.frankel.ch Reference: https://blog.frankel.ch/writing-for-developers/?ref=dailydev date created: 2025-06-19 09:11 --- # Title: Review of "Writing for Developers" by Piotr Sarna and Cynthia Dunlop ## Table of Contents: - [📝 Summary](#📝-summary) - [📖 Main Content](#📖-main-content) - [🗒️ Notes](#🗒️-notes) - [📖 References](#📖-references) - [🗣️ Paraphrase](#🗣️-paraphrase) - [📰 Newsletter](#📰-newsletter) - [✅ Action Items](#✅-action-items) - [🧪 Hypotheses](#🧪-hypotheses) - [📊 Methodology](#📊-methodology) - [❓ Questions](#❓-questions) - [🔮 Future Research](#🔮-future-research) - [💡 Implications](#💡-implications) - [🧠 Learning Styles Assessment](#🧠-learning-styles-assessment) - [📊 Accessibility Assessment](#📊-accessibility-assessment) - [🌍 DEIB (Diversity, Equity, Inclusion, and Belonging) Assessment](#🌍-deib-diversity-equity-inclusion-and-belonging-assessment) - [✅ Logical validity](#✅-logical-validity) - [🔍 DARVO Analysis Prompt](#🔍-darvo-analysis-prompt) - [🔍 SEO Evaluation](#🔍-seo-evaluation) - [🎯 Conclusion](#🎯-conclusion) --- ## 📝 Summary: This review of "Writing for Developers" by Piotr Sarna and Cynthia Dunlop explores the book's structure, content, and utility for technical writers, developer advocates, and developers interested in blogging. The reviewer, Nicolas Fränkel, highlights the book’s strengths in demystifying writing for developers, particularly through its detailed breakdown of blog post patterns. While praising its practical approach and comprehensive typologies, the reviewer notes a minor annoyance with repeated warnings about company confidentiality. The overall recommendation is positive, especially for those new to technical writing or seeking to systematize their approach. --- ## 📖 Main Content: "Writing for Developers" is dissected by a seasoned technologist who has witnessed the evolution of developer content from sparse documentation to a thriving landscape of technical blogs and dedicated writer roles. The book is organized into four parts: fundamentals, the writing process, blog post patterns, and promotion/adaptation. The reviewer appreciates the book’s practical guidance and especially its taxonomy of blog post types, which provides a useful framework for both novice and experienced writers. The only significant critique is the repetitive caution against disclosing company secrets, which the reviewer finds a bit patronizing. However, the book’s actionable advice, pattern-based approach, and relevance to modern developer communication make it a valuable resource. ### 🗒️ Notes - **Book Structure** - 17 chapters in four parts, plus two appendices. - Part 1: Fundamentals of technical writing. - Part 2: The writing process—drafting, optimizing, feedback, publishing. - Part 3: Patterns for blog posts, including "Bug Hunt," "Rewrote It in X," "Lessons Learned," and more. - Part 4: Promotion, adaptation, and expansion (e.g., turning posts into talks or books). - **Highlights** - Addresses common developer objections to writing, with counter-arguments. - Detailed typology of blog post patterns, each with purpose, audience, examples, characteristics, and dos/don’ts. - Practical for both beginners and experienced writers. - Useful for anyone contributing to developer blogs or technical documentation. - **Critiques** - Repetitive reminders about not disclosing company secrets felt excessive. - Part four less relevant for those already familiar with cross-posting and content reuse. - **Recommendation** - Strongly recommended for technical writers, developer advocates, and developers interested in blogging. --- ## 📖 References: - Fränkel, N. (2024). "Writing for Developers" Review. Retrieved from https://blog.frankel.ch/writing-for-developers/?ref=dailydev - Sarna, P., & Dunlop, C. (2024). Writing for Developers. Manning Publications. --- ## 🗣️ Paraphrase: 1. **Original:** "In the first chapter, the authors list the most common reasons developers mention not to write posts. I have heard many of these reasons and can confirm their existence. Then, the authors address each of them and provide multiple counter-arguments." **Paraphrased:** The book opens by outlining the typical excuses developers give for avoiding writing. Having encountered these myself, I can vouch for their prevalence. The authors then systematically tackle each excuse, offering several persuasive rebuttals. 2. **Original:** "Part three is dedicated to blog post _patterns_; each chapter describes a pattern in detail. Reading this made me realize that most blog posts fall into a specific and easily identifiable category." **Paraphrased:** The third section focuses entirely on different blog post templates, with each chapter delving into a particular style. This analysis made me recognize that the majority of blog posts actually fit neatly into a handful of recognizable types. --- ## 📰 Newsletter: **Writing for Developers: A Must-Read for Aspiring Tech Writers** Looking to sharpen your technical writing chops or finally start that developer blog? Nicolas Fränkel’s review of "Writing for Developers" by Piotr Sarna and Cynthia Dunlop is your friendly nudge to dive in. The book breaks down the writing process, demystifies common developer hang-ups, and—best of all—lays out a smorgasbord of blog post patterns, from "Bug Hunts" to "Lessons Learned." Whether you’re a seasoned dev advocate or just dipping your toes into content creation, this guide has actionable tips to up your writing game. Bonus: it even covers how to turn your posts into conference talks or books. Check out the full review and grab the book if you’re ready to make your mark in the dev blogosphere! Read more: [Writing for Developers Review](https://blog.frankel.ch/writing-for-developers/?ref=dailydev) --- ## ✅ Action Items: - **Open Source Advocacy:** The book’s emphasis on clear, structured communication directly supports onboarding and mentoring new contributors, a cornerstone of sustainable open-source communities. - **Contributor Engagement:** By breaking down writing into approachable patterns, it empowers more developers to share knowledge, which can boost engagement and foster a culture of documentation and transparency. - **Education:** The systematic approach to technical writing aligns with instructional design best practices, making it easier to teach and model for new contributors. - **OSPO Director Aspirations:** Mastery of technical communication is critical for leading open source programs, advocating for best practices, and ensuring inclusivity. The book’s focus on patterns and process can be leveraged to standardize documentation and knowledge sharing across teams. - **Transparency & Inclusivity:** The review’s critique of repetitive reminders about confidentiality underscores the need for balanced, respectful communication—essential for psychological safety and trust in diverse open-source ecosystems. - **WordPress Ecosystem:** The actionable advice and content reuse strategies are directly applicable to community blogs, documentation sprints, and contributor onboarding in WordPress and beyond. --- ## 🧪 Hypotheses: - Developers provided with clear blog post patterns will be more likely to contribute technical content. - Structured writing frameworks reduce the perceived barriers to technical writing among software engineers. - Repeated warnings about confidentiality may decrease reader engagement or perceived autonomy. ### 📊 Methodology: - **Surveys**: Pre- and post-intervention surveys to measure changes in willingness to write among developers exposed to pattern-based writing guides. - **A/B Testing**: Compare engagement and output between groups using the book’s frameworks and those without. - **Content Analysis**: Review developer blogs for increases in pattern-based posts after book adoption. - **Interviews**: Qualitative interviews with technical writers and developer advocates. ### ❓ Questions: - What are the most common obstacles developers face when starting to write? - Ho - Summary: I started this blog as a hobby seventeen years ago, in April 2008. At the time, I had no clue about technical writing. I’m pretty sure it was not even a thing back then: the only content aimed at developers was technical documentation. Since then, the landscape has changed a lot, to the point that companies hire for technical writer positions. I was curious to compare what I learned by doing to the structured approach of a book. I ordered the book last year when it was still being written - URL: https://blog.frankel.ch/writing-for-developers/?ref=dailydev May 25, 2025 [TECHNICAL WRITING](https://blog.frankel.ch/tag/technical-writing/) [BLOG](https://blog.frankel.ch/tag/blog/) | | | | --- | --- | | | Disclaimer This post includes affiliate links; I may receive compensation if you purchase the book from the different links provided in this post. | This review is about [Writing for Developers](https://www.manning.com/books/writing-for-developers?utm_source=frankel&utm_medium=affiliate&utm_campaign=affiliate&a_aid=frankel) by Piotr Sarna and Cynthia Dunlop from Manning. I started this blog as a hobby seventeen years ago, in April 2008. At the time, I had no clue about technical writing. I’m pretty sure it was not even a thing back then: the only content aimed at developers was technical documentation. Since then, the landscape has changed a lot, to the point that companies hire for technical writer positions. I was curious to compare what I learned by doing to the structured approach of a book. I ordered the book last year when it was still being written. It was published only early this year, and I was already reading (and reviewing!) [DuckDB in action](https://blog.frankel.ch/duckdb-in-action/). I put it on the top of my reading pile list; I finally finished it: here’s my review. #### Facts * 17 chapters, divided into four parts * 2 appendices * 345 pages * $39.99 (eBook) #### Chapters Part 1 - Fundamentals 1. Why write 2. What to write 3. Captivating readers Part 2 - Nailing the writing process 1. Creating your working draft 2. Optimizing your draft 3. Getting feedback 4. Ship it Part 3 - Applying the blog post pattern 1. The "Bug Hunt" pattern 2. The "Rewrote It in X" pattern 3. The "How We Built It" pattern 4. The "Lessons Learned" pattern 5. The "Thoughts on Trends" pattern 6. The "Non-markety Product Perspectives" pattern 7. The "Benchmarks and Test Results" pattern Part 4 - Promotion, adaptation, and expansion 1. Getting attention 2. From blog post to conference talk 3. So you want to write a book #### Pros and cons * In the first chapter, the authors list the most common reasons developers mention not to write posts. I have heard many of these reasons and can confirm their existence. Then, the authors address each of them and provide multiple counter-arguments. * Part three is dedicated to blog post *patterns*; each chapter describes a pattern in detail. Reading this made me realize that most blog posts fall into a specific and easily identifiable category. The authors structured each pattern-chapter into the following sections: + Purpose: what’s the idea (or ideas) behind the pattern + Audience: who does the pattern target + Examples: a couple of existing blog posts that embody the pattern + Characteristics: common traits found among the posts of this type + Dos and don’ts I do love typologies, and I found this breakdown very useful. * I found part four less relevant, especially since cross-posting has been part of my workflow for ages, and I reuse writing content for conference talks. If you never considered these options, you’ll benefit from these chapters. * The only con I found is that the authors remind us that you should ask your company before you reveal trade secrets. I understand that you would like to warn people, but when it’s repeated several times throughout the book, I got the feeling they’re writing to dummies–not something I’m fond of. #### Summary If you’re a technical writer, a Developer Advocate tasked with technical writing, or a regular developer who wants to start a blog or contribute to a company blog, I recommend getting this book. The exhaustive description of common patterns is a huge asset for beginning writers and can help even seasoned ones. Nicolas Fränkel is a technologist focusing on cloud-native technologies, DevOps, CI/CD pipelines, and system observability. His focus revolves around creating technical content, delivering talks, and engaging with developer communities to promote the adoption of modern software practices. With a strong background in software, he has worked extensively with the JVM, applying his expertise across various industries. In addition to his technical work, he is the author of several books and regularly shares insights through his blog and open-source contributions. Some content could not be imported from the original document. [View content ↗](https://disqus.com/recommendations/?base=default&f=blog-frankel&t_u=https%3A%2F%2Fblog.frankel.ch%2Fwriting-for-developers%2F%3Fref%3Ddailydev&t_d=Writing%20for%20Developers&t_t=Writing%20for%20Developers#version=503d69c4577fa60689280de87df5f22d) Some content could not be imported from the original document. [View content ↗](https://disqus.com/embed/comments/?base=default&f=blog-frankel&t_i=Writing%20for%20Developers&t_u=https%3A%2F%2Fblog.frankel.ch%2Fwriting-for-developers%2F&t_d=Writing%20for%20Developers&t_t=Writing%20for%20Developers&s_o=default#version=d4d839c18c5b97e46e56669525046a4c) [Jun 1, 2025 #### Runtime-initialized variables in Rust Rust offers different ways to initialize compile time-initialized variables. Recently, I had to create a runtime-initialized variable: existing approaches don’t work in this case. I want to describe multiple ways to achieve it in this post. Constants The Rust language allows you to create constants. Two keywords are available: const and static. Sometimes a certain value is used many times throughout a program, and it can become inconvenient to copy it over and over. What’s more, it’](https://blog.frankel.ch/lazy-initialized-vars-rust/) [Nicolas Fränkel](https://blog.frankel.ch/me/) [May 18, 2025 #### Getting a single value from a device's state in Home Assistant This is the 7th post in the My journey with Home Assistant focus series. I recently acquired Netatmo smart radiator valves to manage my rooms' temperature remotely. I’m not skilled at manual tasks, but I could easily replace the old thermo-static valves. I then registered the smart ones in the Netatmo app. Finally, I integrated them in my Home Assistant via the dedicated Netatmo integration. Everything was very straightforward. I noticed that each valve not only allows remote control but al](https://blog.frankel.ch/home-assistant/7/) [A Java geek](https://blog.frankel.ch/) © 2008-2025 v. 8997d94f0866468d209cd416206d5f417aabd4ed/10394121692 [Latest Posts](https://blog.frankel.ch/), Writing for Developers, Nicolas Fränkel, 01jy45165k0h65pewjgyyp9g8f.