How to write scintillating technical blog posts
Adhere to just a few simple principles and your content may just have a fighting chance
I hate to say it, but there’s no magical template for writing technical blog posts, no silver bullet for garnering tons of clicks and retweets, getting to the top of Hacker News and staying there for hours, and engaging and endearing influencers and ordinary readers alike. There’s a lot of luck involved and even the most technically brilliant, carefully crafted posts can fall flat and go nowhere. C’est la vie.
Nonetheless, my experience strongly suggests that following a handful of basic principles can help you find a solid footing when creating new content and, from time to time, ending up with a traffic- and credibility-generating winner on your hands.
Why listen to me?
Apologies for tooting my own horn, but I should briefly establish some bona fides, lest I fall victim to “those who can’t do teach” accusations.
I’ve been around the block. I’ve written technical blog posts for a wide variety of outlets, including the CNCF blog, the Envoy proxy blog, the CenturyLink Developer Center blog, the Streamlio blog, the Basho blog, and many more. My posts have been read by hundreds of thousands if not millions of times. Just this last month my post on the GA release of gRPC-Web for the CNCF blog topped Hacker News for about half a day, which shows that I’ve still got it. I also recently co-authored the second edition of Seven Databases in Seven Weeks: A Guide to Modern Databases and the NoSQL Movement.
I’m not the top dog in the industry by any stretch but I’ve been at it for a while now and I often do get results, so maybe don’t completely disregard my advice 😎
#1: Diagram it
Really solid technical diagrams are essential to good technical blog posts. A carefully crafted visual stimulus shows that you’ve put in the time and are trying to tell a story. It doesn’t really matter how you make them. I prefer Lucidchart but OmniGraffle, draw.io, and a host of others should do the job just fine.
But a bad diagram — off-center labels, bizarre color scheme, shoddy cropping, lazy conception — will make your post seem amateurish.
“But my post isn’t that technical. Do I really need a diagram?” Yes, even if your post is somewhat technical but doesn’t require a deep dive into something complex. Including a diagram that displays a simple list of features or a Venn diagram, for example, can go a long way if it’s well done and on brand.
#2: Keep your text succinct
A good technical blog post is not like a standard essay or article. Even if it presents a “deep dive” into a specific domain, the average reader will likely be perusing it alongside 50 other browser tabs, not reading it carefully. If you have a post that is more like an essay or article, make sure it to tag it as such and maybe even provide a warning (or find a different venue for that material).
Some tips on keeping your text neat and clean:
- Paragraphs should almost always be three sentences or fewer. If it feels like your paragraphs should be longer, restructure the content until the short-paragraph model fits.
- If a sentence contains a list that’s any more complex than something like “apples, oranges, and bananas” then turn it into a bulleted list
- Sentences should be succinct and to the point. At any point in time it should be clear what the subject, verb, and object of the sentence are. Watch out for dangling instances of “it” and “they;” both are just fine but can easily produce meandering messes.
- If a list starts getting unwieldy, consider using a table instead
#3: It’s not documentation and it’s not marketing copy
Good technical blog posts have a relaxed, personal, human tone and a clear narrative. They describe overcoming challenges or reaching an epiphany or learning a lesson the hard way. They have a limited scope and point to external resources when they start getting too specific.
Documentation tends to be less personal and is meant to be exhaustive—to list every configurable parameter, to provide setup steps for every operating system, to describe the role of every system component. Technical blog posts, on the other hand, are specific and limited. They point to, say, two or three CLI commands rather than all the available commands; they highlight the most powerful “a-ha!” function in a library rather than covering the whole API.
Marketing copy is even more of an anti-model for good technical blog content. In fact, technical blog content should be targeted to people who are averse to marketing and can smell BS a mile away. So don’t mindlessly list features, dive into them: explore their rationale and implementation and acknowledge limitations. Don’t slavishly parrot buzzwords, delve into and even challenge buzzwords. And follow #4 below at all times.
Sometimes you do need to use your blog for marketing copy, of course. That’s fine. Just make it clear that those posts are announcements. Don’t tag them as technical or “deep dive” unless they really are.
#4: Be specific
Related to #3 above, specificity is less important in marketing copy. In a marketing or announcement blog post it’s okay to use general positive terms (“lightweight,” “portable,” “modular”). But terms like this make for extremely dull and amorphous technical content.
Don’t say that your JavaScript library is “lightweight,” say that it’s “only 10 kilobytes when minified, which is 20% smaller than the closest alternative.” Don’t say that your database is “portable,” say that it “can be deployed on Kubernetes, Mesos, or Nomad using just a few CLI commands.” Don’t say that your architecture is “modular,” say that it “is divided up into three services—an auth service, a database interaction layer, and a query service—that can be scaled and managed independently of one another.”
As for buzzwords, it should go without saying that they should be used carefully. Buzzwords almost by definition violate the principle of specificity. Don’t say that your database is “cloud native,” say that it’s easily deployable on Kubernetes and its components are available on Docker Hub. Don’t say that your library is for “Big Data” use cases, say that it can do N operations per second on an HBase column.
#5: Provide a clear narrative arc
Good technical blog content always has an agent: a company, a team, a governing body, a developer, a site reliability engineer. That agent has accomplished something or sought to accomplish something. They’ve succeeded or failed. And now they’re here to share their findings with the world.
The story doesn’t have to be grandiose. It doesn’t have to be “our SRE team sought to transform our entire understanding of how monitoring and observability should be practiced in large organizations.” It could be as simple as “I’m in charge of front-end development and I wanted to enable my team to create smaller asset bundles on web pages.”
Conclusion: display, narrate, limit, specify
I’ll crystallize each of the pointers I gave above into an action item:
- Find something in your post that can be turned into a nice diagram and spend the time to make that diagram sing. Take the time to learn a diagramming tool inside and out and soon enough you’ll be able to crank out beautiful diagrams in 15–20 minutes.
- Read your entire post out loud to weed out clunky wording. Make sure that your paragraphs and sentences adhere to the guidelines above.
- Make sure that nothing in your post is doing work that your documentation or marketing copy should be doing. If you’re digging too far into the weeds, link to your docs. If you’re stringing together superlatives, mark the post as an announcement.
- Eliminate generic superlatives. Avoid buzzwords where possible; if you can’t avoid them, make their contextual usage clear.
- Figure out who the agent in your post is—a hero, an anti-hero, a casual observer, a decision maker—and place that agent at the center. If you can’t find an agent then sorry but you probably don’t have a compelling post.
That’s it for now. I’ll provide a follow-up post to make this all more concrete very soon. Enjoy! If you think of any other pointers, tweet to me @lucperkins.
