Writing for Developers: Blogs that get read

Writing for Developers
brief contents
contents
foreword
preface
acknowledgments
about this book
	Who should read this book
	How this book is organized: A road map
	liveBook discussion forum
	Other online resources
about the authors
about the cover illustration
Part 1
	1 Why write
		1.1	Why write engineering blog posts
			1.1.1	Leaving your comfort zone
			1.1.2	Really understanding your code
			1.1.3	Free peer review
			1.1.4	Personal brand boost
			1.1.5	Career development
			1.1.6	Staying on top of the latest technologies
			1.1.7	Improving your skills
			1.1.8	Attracting new hires
			1.1.9	Attracting users for a developer-focused product
			1.1.10	Write once, share everywhere
			1.1.11	Writing ≠ riches
		1.2	Why write: A personal perspective
		1.3	Excuses for not writing
			1.3.1	Not a writer
			1.3.2	Not even a native English speaker
			1.3.3	No time
			1.3.4	The project isn’t 100% completed
			1.3.5	We don’t even have a product out yet
			1.3.6	It’s not new
			1.3.7	It’s already available as a recorded talk
			1.3.8	Don’t want to leak confidential details
			1.3.9	Nothing interesting to say
		1.4	The path forward
	2 What to write
		2.1	Prioritizing ideas: The 3 Ps
		2.2	Topics, topics, everywhere
			2.2.1	That cool thing you implemented
			2.2.2	A security incident post-mortem
			2.2.3	How your infrastructure survived a traffic spike (or didn’t)
			2.2.4	Bug hunting
			2.2.5	An open source contribution
			2.2.6	A fun weekend project
			2.2.7	An interesting design decision and tradeoff you made
			2.2.8	An architectural shift you’re making
			2.2.9	Frustration and fatigue
			2.2.10	Take a stand on some contentious topic
			2.2.11	Sweet numbers
			2.2.12	Propose using something in an unexpected way
			2.2.13	Revisit past predictions
			2.2.14	Capability clarification
			2.2.15	Capability comparison
			2.2.16	Footgun prevention
			2.2.17	Why you’re building something
		2.3	Increasing your trigger exposure
			2.3.1	Social media
			2.3.2	Virtual communities
			2.3.3	Feeds and subscriptions
			2.3.4	Team chat apps
	3 Captivating readers
		3.1	Standing out
		3.2	Critical characteristics
			3.2.1	Intriguing topic
			3.2.2	Distinctive educational core
			3.2.3	Smooth delivery
		3.3	Examples
			3.3.1	A Search Engine in 80 Lines of Python
			3.3.2	Async Rust is a Bad Language
			3.3.3	Python 3.13 Gets a JIT
			3.3.4	I Have Written a JVM in Rust
			3.3.5	The Return of the Frame Pointers
Part 2
	4 Creating your working draft
		4.1	Focus and challenges
		4.2	Essential prep
			4.2.1	Getting a feel for how others approach the topic
			4.2.2	Getting a feel for what the site publishes
			4.2.3	Defining your goal
		4.3	Optional warmup
			4.3.1	Outlining
			4.3.2	Mindmapping
			4.3.3	Working from a model article
			4.3.4	Copying/pasting your notes
		4.4	Writing time
			4.4.1	Getting words on the page
			4.4.2	Eliminating blockers
		4.5	PretendPiotr’s first attempt at the example blog post
			4.5.1	Zig helped us migrate our data efficiently
		4.6	Filling in gaps
			4.6.1	Did you actually cover what you intended to cover?
			4.6.2	What else should you cover?
			4.6.3	What’s preventing it from being viable?
		4.7	If you do nothing else
	5 Optimizing your draft
		5.1	Focus and challenges
		5.2	Core (focus, flow, facts)
			5.2.1	Facts
			5.2.2	Focus
			5.2.3	Flow
		5.3	Clarity
			5.3.1	Targeting unclear bulky sentences
			5.3.2	Optimizing unclear bulky sentences
			5.3.3	Grappling with grammar
			5.3.4	Putting it all together in a process
		5.4	Components
			5.4.1	Titles
			5.4.2	Introductions
			5.4.3	Endings
			5.4.4	Headings
			5.4.5	Visuals
			5.4.6	Code
		5.5	Consumability
			5.5.1	Keeping it human
			5.5.2	Making it scannable by humans
		5.6	If you do nothing else
	6 Getting feedback
		6.1	Focus and challenges
		6.2	Comparing writing review with code review
		6.3	Selecting your reviewer(s)
		6.4	Deciding when to start
			6.4.1	How important and/or controversial is the topic?
			6.4.2	Do you have a true “blocker” question?
			6.4.3	Do you feel like you’ve done what you intended to do?
			6.4.4	Will there be time for another review cycle after your tech reviewer finishes?
		6.5	Preparing your reviewers
			6.5.1	Providing background
			6.5.2	Specifying what you want
		6.6	Responding to reviewer comments
		6.7	Special steps for special cases
			6.7.1	Nonnative English speakers
			6.7.2	Don’t know who to ask
			6.7.3	Other organizations involved
		6.8	If you do nothing else
	7 Ship it
		7.1	Focus and challenges
		7.2	Read through the core content one final time
		7.3	Preview in place
			7.3.1	Title and headings
			7.3.2	Code
			7.3.3	Core images
			7.3.4	Header image
			7.3.5	Videos
			7.3.6	Tables and lists
		7.4	Manage metadata
			7.4.1	Your keywords
			7.4.2	Title tag
			7.4.3	Meta description
			7.4.4	URL
			7.4.5	Hyperlinks
			7.4.6	Images
			7.4.7	Taxonomies: Categories, tags, and topics
			7.4.8	Featured (thumbnail) images
		7.5	If you do nothing else
Part 3
	8 The “Bug Hunt” pattern
		8.1	Purpose
			8.1.1	Knowledge dump
			8.1.2	Global bug awareness
			8.1.3	Bragging
		8.2	Audience
		8.3	Examples of bug-hunting blog posts
			8.3.1	Hunting a NUMA Performance Bug
			8.3.2	Why Is My Rust Build So Slow?
			8.3.3	How a Single Line of Code Made a 24-core Server Slower Than a Laptop
			8.3.4	Lessons from Debugging a Tricky Direct Memory Leak
			8.3.5	ZFS Is Mysteriously Eating My CPU
		8.4	Characteristics
			8.4.1	Crafted chronologically
			8.4.2	Heavy on the hunt
			8.4.3	Evidence everywhere
			8.4.4	Expert friendly
			8.4.5	Educational
		8.5	Dos and don’ts
			8.5.1	Check if anyone (your boss, your boss’ lawyers) will be upset by your transparency
			8.5.2	Do a technical deep dive
			8.5.3	Be brutally honest about all your failures
			8.5.4	Include numbers, benchmarks, metrics, and flame graphs
			8.5.5	Don’t give away too much, too soon—keep the tension building
			8.5.6	Don’t make overeager readers hunt too hard for the fix
			8.5.7	Add breaking points wherever necessary
			8.5.8	Don’t suck the life out of it
			8.5.9	Don’t forget to thank those who helped along the hunt
			8.5.10	Extrapolate
	9 The “Rewrote It in X” pattern
		9.1	Purpose
			9.1.1	Evangelism
			9.1.2	Project promotion
			9.1.3	Community development
			9.1.4	Ranting
		9.2	Audience
		9.3	Examples of “We Rewrote It in X” blog posts
			9.3.1	Why I Rewrote My Rust Keyboard Firmware in Zig: Consistency, Mastery, and Fun
			9.3.2	How Turborepo is Porting from Go to Rust
			9.3.3	Why Discord Is Switching From Go to Rust
			9.3.4	From Zero to 10 Million Lines of Kotlin
			9.3.5	Why We at $FAMOUS_COMPANY Switched to $HYPED_TECHNOLOGY
		9.4	Characteristics
			9.4.1	Suitable for language newbies
			9.4.2	Practical
			9.4.3	Tremendously templated structure
		9.5	Dos and don’ts
			9.5.1	Start by explaining your rewrite motivation
			9.5.2	Provide background on your project
			9.5.3	Don’t gloss over the rough parts
			9.5.4	Share the resources you used
	10 The “How We Built It” pattern
		10.1	Purpose
			10.1.1	Pioneering
			10.1.2	Flexing muscles
			10.1.3	Free peer review
		10.2	Audience
		10.3	Examples of “How We Built It” blog posts
			10.3.1	How Prime Video Updates its App for More Than 8,000 Device Types
			10.3.2	Twitter’s Recommendation Algorithm
			10.3.3	How We Built Notification Rate Limiter for Eight Billion Notifications Per Day for 400 Million Monthly Active Users
			10.3.4	How We Built Scalable Spatial Data and Spatial Indexing in CockroachDB
			10.3.5	Ship Shape
		10.4	Characteristics
			10.4.1	Not always reproducible
			10.4.2	Serve as a knowledge base
			10.4.3	Pluralis maiestatis
			10.4.4	inb4
		10.5	Dos and don’ts
			10.5.1	Agree on the scope early
			10.5.2	Make graphics a first-class citizen
			10.5.3	Don’t rush it
			10.5.4	Prepare for (un)constructive criticism
	11 The “Lessons Learned” pattern
		11.1	Purpose
			11.1.1	Self-reflection
			11.1.2	Storytelling
			11.1.3	Kickstart
		11.2	Audience
		11.3	Examples of “Lessons Learned” blog posts
			11.3.1	25% or 6 to 4: The 11/6/23 Authentication Outage
			11.3.2	Herding Elephants: Lessons Learned from Sharding Postgres at Notion
			11.3.3	Something You Probably Want to Know About if You’re Using SQLite in Golang
			11.3.4	Lessons Learned Scaling PostgreSQL Database to 1.2bn Records/Month
			11.3.5	Lessons from Stripe
		11.4	Characteristics
			11.4.1	Diary-like
			11.4.2	Imprintable
			11.4.3	Reflections and ruminations
		11.5	Dos & don’ts
			11.5.1	Be humble
			11.5.2	Don’t forget
			11.5.3	Don’t turn on full diary mode
			11.5.4	11.5.4 Encourage interaction
	12 The “Thoughts on Trends” pattern
		12.1	Purpose
			12.1.1	Continuous delivery
			12.1.2	Retrospection
			12.1.3	Shaping the future
		12.2	Audience
		12.3	Examples of “Thoughts on Trends” blog posts
			12.3.1	I Want Off Mr. Golang’s Wild Ride
			12.3.2	How to Think About WebAssembly (Amid the Hype)
			12.3.3	Rust After the Honeymoon
			12.3.4	Software Architecture is Overrated, Clear and Simple Design is Underrated
			12.3.5	How io_uring and eBPF Will Revolutionize Programming in Linux
		12.4	Characteristics
			12.4.1	Opinionated and persuasive
			12.4.2	Provocative
			12.4.3	Idiosyncratic
		12.5	Dos & don’ts
			12.5.1	Be famous
			12.5.2	Consider the elements of persuasion
			12.5.3	Be bold
			12.5.4	Roast
			12.5.5	Don’t just roast
			12.5.6	Don’t just praise
	13 The “Non-markety Product Perspectives” pattern
		13.1	Purpose
			13.1.1	Product placement
			13.1.2	Teaser
			13.1.3	Hiring
		13.2	Audience
		13.3	Examples
			13.3.1	We Put a Distributed Database in a Browser
			13.3.2	32 Bit Real Estate
			13.3.3	System Dependencies Are Hard (So We Made Them Easier)
			13.3.4	Why fsync(): Losing Unsynced Data on a Single Node Leads to Global Data Loss
			13.3.5	So You Think You Want to Write a Deterministic Hypervisor?
		13.4	Characteristics
			13.4.1	Technical
			13.4.2	Behind the scenes
			13.4.3	Subliminal
		13.5	Dos & don’ts
			13.5.1	Introduce yourself
			13.5.2	Don’t sell
			13.5.3	Be balanced but don’t bash
	14 The “Benchmarks and Test Results” pattern
		14.1	Purpose
			14.1.1	Benchmarketing
			14.1.2	Subtle benchmarketing
			14.1.3	Community service
		14.2	Audience
		14.3	Examples of “Benchmarks and Test Results” blog posts
			14.3.1	AWS Graviton2: Arm Brings Better Price-Performance than Intel
			14.3.2	The relative performance of C and Rust
			14.3.3	Redpanda vs. Kafka: A Performance Comparison
			14.3.4	The Effect of Switching to TCMalloc on RocksDB Memory Use
			14.3.5	How Much Does Rust’s Bounds Checking Actually Cost?
		14.4	Characteristics
			14.4.1	Numeric and visual
			14.4.2	Guilty until proven innocent
			14.4.3	Quasi academic
		14.5	Do’s & don’ts
			14.5.1	Read Brendan Gregg’s “Systems Performance”
			14.5.2	Show how to reproduce the results
			14.5.3	Don’t exaggerate
			14.5.4	Don’t neglect
			14.5.5	Boil it down, spell it out
Part 4
	15 Getting attention
		15.1	Choose your own adventure
		15.2	Sharing across social and virtual communities
			15.2.1	Connecting with the community
			15.2.2	Sharing (and discussing) your blog post
			15.2.3	Keeping it alive
		15.3	Publishing in selective tech publications
			15.3.1	Why bother?
			15.3.2	Why not?
			15.3.3	Considerations
			15.3.4	Tips
		15.4	Syndicating simulacra
			15.4.1	Why bother?
			15.4.2	Why not?
			15.4.3	Considerations
			15.4.4	Tips
		15.5	Guest blogging
			15.5.1	Why bother?
			15.5.2	Why not?
			15.5.3	Considerations
			15.5.4	Tips
		15.6	Participating in podcasts and livestreams
			15.6.1	Why bother?
			15.6.2	Why not?
			15.6.3	Considerations
			15.6.4	Tips
		15.7	Sharing at conferences
		15.8	Measuring the effects
			15.8.1	The blog post
			15.8.2	How people are finding the blog post
			15.8.3	Who’s reading and how
			15.8.4	Social and community engagements
	16 From blog post to conference talk
		16.1	The path to speaking
			16.1.1	Piotr’s path
			16.1.2	Why speak at conferences?
			16.1.3	Why not?
		16.2	Identifying and evaluating opportunities
			16.2.1	Fit
			16.2.2	Reach and promotion
			16.2.3	Logistics
		16.3	Submitting your proposal
			16.3.1	Reusing/rethinking your blog post
			16.3.2	Submission tips
		16.4	Converting your blog post to a talk
			16.4.1	Start with the most important takeaway
			16.4.2	Map out the slide flow
			16.4.3	Develop individual slides
			16.4.4	Prepare speaker notes
		16.5	Promoting the talk
		16.6	Rehearsing
		16.7	Delivering
		16.8	Following Up
	17 So you want to write a book
		17.1	Why write a book?
			17.1.1	You have a vision for a book that begs to be written
			17.1.2	You want to anchor yourself as an expert
			17.1.3	You want an excuse to immerse yourself in a topic
			17.1.4	You want to level up your writing
			17.1.5	You have an innate urge to share and teach
		17.2	Why not?
			17.2.1	The topic isn’t well-suited to a book
			17.2.2	It’s just not a great fit for you—at least not right now
		17.3	Alternatives to consider
			17.3.1	Collaborate with co-authors
			17.3.2	Drip it out through blog posts
			17.3.3	Become a technical reviewer
		17.4	Publishing considerations
			17.4.1	Not all publishers are created equal
			17.4.2	Publishers bring an impressive team of experts
			17.4.3	Working with publishers is a multithreaded process
			17.4.4	If you work with a publisher, it’s not just “your” book
			17.4.5	Highly specialized topics lend themselves to self-publishing
			17.4.6	Self-publishing thrives when supported by a brand
			17.4.7	Different options, different considerations
		17.5	Navigating the proposal process
			17.5.1	Get down to business
			17.5.2	Details, detail, details
		17.6	Go forth and write
appendix A
appendix B
afterword
index