|
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 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. 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
- Why write
- What to write
- Captivating readers
Part 2 - Nailing the writing process
- Creating your working draft
- Optimizing your draft
- Getting feedback
- Ship it
Part 3 - Applying the blog post pattern
- The "Bug Hunt" pattern
- The "Rewrote It in X" pattern
- The "How We Built It" pattern
- The "Lessons Learned" pattern
- The "Thoughts on Trends" pattern
- The "Non-markety Product Perspectives" pattern
- The "Benchmarks and Test Results" pattern
Part 4 - Promotion, adaptation, and expansion
- Getting attention
- From blog post to conference talk
- 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.