Writing for Developers Blogs that get read (Piotr Sarna, Cynthia Dunlop) (Z-Library)

📄 File Format: PDF

💾 File Size: 16.0 MB

📖 Read Online ⬇️ Download

Registered users can read the full content for free

Register as a Gaohf Library member to read the complete e-book online for free and enjoy a better reading experience.

📄 Page 1

M A N N I N G Piotr Sarna Cynthia Dunlop Foreword by Bryan Cantrill Afterword by Scott Hanselman Blogs that get read

📄 Page 2

Blog post patterns covered in this book “Bug Hunt” posts share the thrill of finding and fixing some elusive bug. Writing a bug-hunting article serves to share knowledge, raise awareness about bugs you encountered, and showcase your achievements. “We Rewrote It in X” posts are all about rewriting an app in a new (and trendy!) programming language, library, or framework. They promote both the rewritten project and its new technology. “How We Built It” posts share your most impressive engineering achievements. Engineers writing about how they built things creates a valuable knowledge base for the community, brick by brick (pun intended). “Lessons Learned” posts share lessons learned from technical challenges. Technical audiences love to learn. And one of the few things they love even more than learning itself is learning from other people's mistakes instead of their own. “Thoughts on Trends” posts are highly opinionated takes on industry trends. They might reflect on the past, try to shape the future, and/or share insights on whatever everyone is obsessing about today. “Non-markety Product Perspectives” posts embed your product into a genuinely intriguing and educational article. The reader learns something even if they never touch your product—but now they’re so intrigued that they want to try it anyway. “Benchmarks and Test Results” posts 1) compare your company's product against its competition, 2) compare something (e.g., infrastructure) using your company's product, or 3) measure something independent of your products.

📄 Page 3

Writing for Developers

📄 Page 4

(This page has no text content)

📄 Page 5

MANN I NG Shelter ISland Writing for Developers Piotr Sarna Cynthia Dunlop Blogs that get read Foreword by Bryan Cantrill Afterword by Scott Hanselman

📄 Page 6

For online information and ordering of this and other Manning books, please visit www.manning.com. The publisher offers discounts on this book when ordered in quantity. For more information, please contact Special Sales Department Manning Publications Co. 20 Baldwin Road PO Box 761 Shelter Island, NY 11964 Email: orders@manning.com © 2025 Manning Publications Co. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by means electronic, mechanical, photocopying, or otherwise, without prior written permission of the publisher. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in the book, and Manning Publications was aware of a trademark claim, the designations have been printed in initial caps or all caps. Recognizing the importance of preserving what has been written, it is Manning’s policy to have the books we publish printed on acid- free paper, and we exert our best efforts to that end. Recognizing also our responsibility to conserve the resources of our planet, Manning books are printed on paper that is at least 15 percent recycled and processed without the use of elemental chlorine. ∞ Manning Publications Co. 20 Baldwin Road PO Box 761 Shelter Island, NY 11964 The author and publisher have made every effort to ensure that the information in this book was correct at press time. The author and publisher do not assume and hereby disclaim any liability to any party for any loss, damage, or disruption caused by errors or omissions, whether such errors or omissions result from negligence, accident, or any other cause, or from any usage of the information herein. Development editor: Doug Rudder Technical editor: Eric Lippert Review editor: Radmila Ercegovac Production editor: Keri Hales Copy editor: Lana Todorovic-Arndt Proofreader: Olga Milanko Typesetter: Tamara ŠveliÊ SabljiÊ Cover designer: Marija Tudor ISBN 9781633436282 Printed in the United States of America

📄 Page 7

To Wiktoria, Aurelia, and… —Piotr To David —Cynthia

📄 Page 8

brief contents Part 1 Fundamentals ..............................................................1 1 ■ Why write 3 2 ■ What to write 19 3 ■ Captivating readers 35 Part 2 Nailing the writing process ....................................47 4 ■ Creating your working draft 49 5 ■ Optimizing your draft 78 6 ■ Getting feedback 120 7 ■ Ship it 131 Part 3 Applying blog post patterns ................................. 153 8 ■ The “Bug Hunt” pattern 155 9 ■ The “Rewrote It in X” pattern 169 10 ■ The “How We Built It” pattern 183 11 ■ The “Lessons Learned” pattern 196 12 ■ The “Thoughts on Trends” pattern 207 13 ■ The “Non-markety Product Perspectives” pattern 220 14 ■ The “Benchmarks and Test Results” pattern 232 vi

📄 Page 9

viibrief contents Part 4 Promotion, adaptation, and expansion ................ 247 15 ■ Getting attention 249 16 ■ From blog post to conference talk 276 17 ■ So you want to write a book 293 A ■ Publishing and writing resources 310 B ■ AI uses and abuses 318

📄 Page 10

contents foreword xviii preface xx acknowledgments xxii about this book xxiv about the authors xxvii about the cover illustration xxviii Part 1 Fundamentals................................................1 1 Why write 3 1.1 Why write engineering blog posts 4 Leaving your comfort zone 4 ■ Really understanding your code 5 ■ Free peer review 5 ■ Personal brand boost 5 Career development 6 ■ Staying on top of the latest technologies 7 ■ Improving your skills 8 ■ Attracting new hires 8 ■ Attracting users for a developer-focused product 9 Write once, share everywhere 9 ■ Writing ≠ riches 9 1.2 Why write: A personal perspective 10 1.3 Excuses for not writing 11 Not a writer 11 ■ Not even a native English speaker 12 No time 13 ■ The project isn’t 100% completed 13 We don’t even have a product out yet 14 ■ It’s not new 14 It’s already available as a recorded talk 15 ■ Don’t want to leak confidential details 15 ■ Nothing interesting to say 16 1.4 The path forward 16 viii

📄 Page 11

ixcontents 2 What to write 19 2.1 Prioritizing ideas: The 3 Ps 20 2.2 Topics, topics, everywhere 21 That cool thing you implemented 21 ■ A security incident post-mortem 22 ■ How your infrastructure survived a traffic spike (or didn’t) 23 ■ Bug hunting 23 ■ An open source contribution 24 ■ A fun weekend project 24 ■ An interesting design decision and tradeoff you made 24 ■ An architectural shift you’re making 25 ■ Frustration and fatigue 26 Take a stand on some contentious topic 26 ■ Sweet numbers 27 Propose using something in an unexpected way 27 ■ Revisit past predictions 28 ■ Capability clarification 28 ■ Capability comparison 29 ■ Footgun prevention 30 ■ Why you’re building something 30 2.3 Increasing your trigger exposure 31 Social media 31 ■ Virtual communities 32 ■ Feeds and subscriptions 33 ■ Team chat apps 33 Captivating readers 35 3 3.1 Standing out 36 3.2 Critical characteristics 37 Intriguing topic 37 ■ Distinctive educational core 38 Smooth delivery 39 3.3 Examples 40 A Search Engine in 80 Lines of Python 40 ■ Async Rust is a Bad Language 41 ■ Python 3.13 Gets a JIT 42 ■ I Have Written a JVM in Rust 43 ■ The Return of the Frame Pointers 44 Part 2 Nailing the writing process ..................... 47 494 Creating your working draft 4.1 Focus and challenges 50 4.2 Essential prep 51 Getting a feel for how others approach the topic 52 ■ Getting a feel for what the site publishes 53 ■ Defining your goal 54 4.3 Optional warmup 57 ticle 60 ■ Copying/pasting your notes 61

📄 Page 12

x contents 4.4 Writing time 62 Getting words on the page 62 ■ Eliminating blockers 64 4.5 PretendPiotr’s first attempt at the example blog post 66 Zig helped us migrate our data efficiently 66 4.6 Filling in gaps 68 Did you actually cover what you intended to cover? 69 What else should you cover? 71 ■ What’s preventing it from being viable? 75 4.7 If you do nothing else 76 5 Optimizing your draft 78 5.1 Focus and challenges 79 5.2 Core (facts, focus, flow) 80 Facts 81 ■ Focus 83 ■ Flow 86 5.3 Clarity 90 Targeting unclear bulky sentences 92 ■ Optimizing unclear bulky sentences 92 ■ Grappling with grammar 101 Putting it all together in a process 102 5.4 Components 103 Titles 103 ■ Introductions 107 ■ Endings 110 Headings 111 ■ Visuals 112 ■ Code 113 5.5 Consumability 114 Keeping it human 114 ■ Making it scannable by humans 116 5.6 If you do nothing else 117 6 Getting feedback 120 6.1 Focus and challenges 121 6.2 Comparing writing review with code review 121 6.3 Selecting your reviewer(s) 122 6.4 Deciding when to start 123 How important and/or controversial is the topic? 124 Do you have a true “blocker” question? 124 ■ Do you feel like you’ve done what you intended to do? 125 ■ Will there be time for another review cycle after your tech reviewer finishes? 125 6.5 Preparing your reviewers 125 Providing background 125 ■ Specifying what you want 126

📄 Page 13

xicontents 6.6 Responding to reviewer comments 128 6.7 Special steps for special cases 129 Nonnative English speakers 129 ■ Don’t know who to ask 129 Other organizations involved 130 6.8 If you do nothing else 130 7 Ship it 131 7.1 Focus and challenges 132 7.2 Read through the core content one final time 132 7.3 Preview in place 133 Title and headings 134 ■ Code 134 ■ Core images 135 Header image 136 ■ Videos 137 ■ Tables and lists 137 7.4 Manage metadata 138 Your keywords 138 ■ Title tag 141 ■ Meta description 142 URL 143 ■ Hyperlinks 144 ■ Images 145 ■ Taxonomies: Categories, tags, and topics 146 ■ Featured (thumbnail) images 148 7.5 If you do nothing else 151 Part 3 Applying blog post patterns .................. 153 8 The “Bug Hunt” pattern 155 8.1 Purpose 155 Knowledge dump 156 ■ Global bug awareness 157 Bragging 157 8.2 Audience 157 8.3 Examples of “Bug Hunt” blog posts 158 Hunting a NUMA Performance Bug 158 ■ Why Is My Rust Build So Slow? 159 ■ How a Single Line of Code Made a 24-core Server Slower Than a Laptop 159 ■ Lessons from Debugging a Tricky Direct Memory Leak 160 ■ ZFS Is Mysteriously Eating My CPU 161 8.4 Characteristics 161 vidence everywhere 162 ■ Expert friendly 164 Educational 164

📄 Page 14

xii contents 8.5 Dos and don’ts 164 Check if anyone (your boss, your boss’ lawyers) will be upset by your transparency 165 ■ Do a technical deep dive 165 Be brutally honest about all your failures 165 ■ Include numbers, benchmarks, metrics, and flame graphs 166 Don’t give away too much, too soon—keep the tension building 166 ■ Don’t make overeager readers hunt too hard for the fix 166 ■ Add breaking points wherever necessary 166 Don’t suck the life out of it 167 ■ Don’t forget to thank those who helped along the hunt 167 ■ Extrapolate 167 9 The “Rewrote It in X” pattern 169 9.1 Purpose 170 Evangelism 170 ■ Project promotion 171 ■ Community development 172 ■ Ranting 172 9.2 Audience 172 9.3 Examples of “We Rewrote It in X” blog posts 173 Why I Rewrote My Rust Keyboard Firmware in Zig: Consistency, Mastery, and Fun 173 ■ How Turborepo is Porting from Go to Rust 174 ■ Why Discord Is Switching From Go to Rust 174 From Zero to 10 Million Lines of Kotlin 175 ■ Why We at $FAMOUS_COMPANY Switched to $HYPED_ TECHNOLOGY 176 9.4 Characteristics 176 Suitable for language newbies 177 ■ Practical 177 Tremendously templated structure 178 9.5 Dos and don’ts 179 Start by explaining your rewrite motivation 179 ■ Provide background on your project 180 ■ Don’t gloss over the rough parts 180 ■ Share the resources you used 181 10 The “How We Built It” pattern 183 10.1 Purpose 184 Pioneering 185 ■ Flexing muscles 185 ■ Free peer review 185 10.2 Audience 186 10.3 Examples of “How We Built It” blog posts 186 How Prime Video Updates its App for More Than 8,000 Device Types 186 ■ Twitter’s Recommendation Algorithm 187

📄 Page 15

xiiicontents How We Built Notification Rate Limiter for Eight Billion Notifications Per Day for 400 Million Monthly Active Users 188 How We Built Scalable Spatial Data and Spatial Indexing in CockroachDB 189 ■ Ship Shape 190 10.4 Characteristics 191 Not always reproducible 191 ■ Serve as a knowledge base 191 Pluralis maiestatis 192 ■ inb4 192 10.5 Dos and don’ts 193 Agree on the scope early 193 ■ Make graphics a first-class citizen 193 ■ Don’t rush it 194 ■ Prepare for (un)constructive criticism 194 11 The “Lessons Learned” pattern 196 11.1 Purpose 197 Self-reflection 197 ■ Storytelling 198 ■ Kickstart 198 11.2 Audience 198 11.3 Examples of “Lessons Learned” blog posts 199 25% or 6 to 4: The 11/6/23 Authentication Outage 199 Herding Elephants: Lessons Learned from Sharding Postgres at Notion 200 ■ Something You Probably Want to Know About if You’re Using SQLite in Golang 201 ■ Lessons Learned Scaling PostgreSQL Database to 1.2bn Records/Month 201 ■ Lessons from Stripe 202 11.4 Characteristics 203 Diary-like 203 ■ Imprintable 204 ■ Reflections and ruminations 204 11.5 Dos & don’ts 204 Be humble 205 ■ Don’t forget 205 ■ Don’t turn on full diary mode 205 ■ Encourage interaction 205 12 The “Thoughts on Trends” pattern 207 12.1 Purpose 208 Continuous delivery 209 ■ Retrospection 209 ■ Shaping the future 209 12.2 Audience 209 12.3 Examples of “Thoughts on Trends” blog posts 210 I Want Off Mr. Golang’s Wild Ride 210 ■ How to Think he

📄 Page 16

xiv contents Honeymoon 212 ■ Software Architecture is Overrated, Clear and Simple Design is Underrated 213 ■ How io_uring and eBPF Will Revolutionize Programming in Linux 214 12.4 Characteristics 215 Opinionated and persuasive 215 ■ Provocative 216 Idiosyncratic 216 12.5 Dos & don’ts 217 Be famous 217 ■ Consider the elements of persuasion 217 Be bold 218 ■ Roast 219 ■ Don’t just roast 219 Don’t just praise 219 13 The “Non-markety Product Perspectives” pattern 220 13.1 Purpose 221 Product placement 222 ■ Teaser 222 ■ Hiring 222 13.2 Audience 222 13.3 Examples of “Non-markety Product Perspectives” blog posts 223 We Put a Distributed Database in a Browser—And Made a Game of It! 223 ■ 32 Bit Real Estate 224 ■ System Dependencies Are Hard (So We Made Them Easier) 225 ■ Why fsync(): Losing Unsynced Data on a Single Node Leads to Global Data Loss 226 ■ So You Think You Want to Write a Deterministic Hypervisor? 226 13.4 Characteristics 227 Technical 228 ■ Behind the scenes 228 ■ Subliminal 228 13.5 Dos & don’ts 229 Introduce yourself 229 ■ Don’t sell 229 ■ Be balanced but don’t bash 230 14 The “Benchmarks and Test Results” pattern 232 14.1 Purpose 234 Benchmarketing 234 ■ Subtle benchmarketing 234 Community service 234 14.2 Audience 235 14.3 Examples of “Benchmarks and Test Results” blog posts 235 AWS Graviton2: Arm Brings Better Price-Performance than Intel 235 ■ The Relative Performance of C and Rust 236

📄 Page 17

xvcontents Redpanda vs. Kafka: A Performance Comparison 237 The Effect of Switching to TCMalloc on RocksDB Memory Use 238 ■ How Much Does Rust’s Bounds Checking Actually Cost? 239 14.4 Characteristics 241 Numeric and visual 241 ■ Guilty until proven innocent 241 Quasi academic 242 14.5 Dos & don’ts 243 Read Brendan Gregg’s “Systems Performance” 243 ■ Show how to reproduce the results 243 ■ Don’t exaggerate 243 ■ Don’t neglect 243 ■ Boil it down, spell it out 244 Part 4 Promotion, adaptation, and expansion .. 247 15 Getting attention 249 15.1 Choose your own adventure 250 15.2 Sharing across social and virtual communities 251 Connecting with the community 252 ■ Sharing (and discussing) your blog post 254 ■ Keeping it alive 260 15.3 Publishing in selective tech publications 260 Why bother? 261 ■ Why not? 262 ■ Considerations 262 Tips 263 15.4 Syndicating simulacra 264 Why bother? 264 ■ Why not? 265 ■ Considerations 265 Tips 265 15.5 Guest blogging 266 Why bother? 266 ■ Why not? 266 ■ Considerations 267 Tips 267 15.6 Participating in podcasts and livestreams 267 Why bother? 268 ■ Why not? 268 ■ Considerations 268 Tips 269 15.7 Sharing at conferences 269 15.8 Measuring the effects 270 The blog post 270 ■ How people are finding the blog post 272 Who’s reading and how 273 ■ Social and community engagements 273

📄 Page 18

xvi contents 16 From blog post to conference talk 276 16.1 The path to speaking 277 Piotr’s path 277 ■ Why speak at conferences? 278 Why not? 279 16.2 Identifying and evaluating opportunities 280 Fit 281 ■ Reach and promotion 281 ■ Logistics 281 16.3 Submitting your proposal 282 Reusing/rethinking your blog post 283 ■ Submission tips 284 16.4 Converting your blog post to a talk 285 Start with the most important takeaway 286 ■ Map out the slide flow 286 ■ Develop individual slides 287 ■ Prepare speaker notes 288 16.5 Promoting the talk 289 16.6 Rehearsing 289 16.7 Delivering 290 16.8 Following up 291 17 So you want to write a book 293 17.1 Why write a book? 294 You have a vision for a book that begs to be written 294 You want to anchor yourself as an expert 295 ■ You want an excuse to immerse yourself in a topic 295 ■ You want to level up your writing 296 ■ You have an innate urge to share and teach 296 17.2 Why not? 296 The topic isn’t well-suited to a book 297 ■ It’s just not a great fit for you—at least not right now 297 17.3 Alternatives to consider 297 Collaborate with co-authors 298 ■ Drip it out through blog posts 299 ■ Become a technical reviewer 300 17.4 Publishing considerations 300 Not all publishers are created equal 301 ■ Publishers bring an impressive team of experts 301 ■ Working with publishers is a multithreaded process 303 ■ If you work with a publisher, it’s not just “your” book 303 ■ Highly specialized topics lend themselves to self-publishing 304 ■ Self-publishing thrives

📄 Page 19

xviicontents when supported by a brand 305 ■ Different options, different considerations 305 17.5 Navigating the proposal process 305 Get down to business 307 ■ Details, detail, details 307 17.6 Go forth and write 308 appendix A Publishing and writing resources 310 appendix B AI uses and abuses 318 afterword 334 index 336

📄 Page 20

foreword “You’re not writing enough.” It was May 31, 2008, and I was at UC Berkeley, listening to Pat Helland eulogize data- base pioneer Jim Gray. (Fittingly, I wrote about attending the tribute: https://mng .bz/Dpln.) Over a year earlier, Gray had been tragically lost at sea and was presumed deceased; the computer science community had now gathered to pay tribute to him, and to the influence he had had on the domain and its practitioners. I had known Gray only by his works, but with each passing speaker, the throughlines of his life emerged: not merely of an exceptional thinker and extraordinary researcher, but of an engaged mentor; a connector; a bridge. Of the recollections, it was Helland relaying being admonished by Gray that I found particularly resonant: He always said, “write, write, write.” He looked at me and said, “Pat, you’re not writ- ing enough.” For twenty years, he told me “You’re not writing enough.” And he was right—and I still tell myself “You’re not writing enough.” —Pat Helland, Tribute to Honor Jim Gray, May 31, 2008 (https://mng.bz/NBvN) Hearing Helland give voice to Gray’s words was a revelation for me: while I had always viewed writing as personally important, Gray pointed me to its larger purpose of serv- ing our collective craft. To write is not just to polish and sharpen our own thinking, but also to collaborate with our fellow practitioners and to bridge to future generations— to share our findings and perspectives so others can benefit from our experience and wisdom, just like we have learned from others. In short, while it is our work that gives us meaning, it is our writing that allows us to connect that meaning in an enduring way to our broader community of practitioners. xviii