Almost exactly two years ago I applied to be a Community Manager at PostHog. (You can read about my application on a Discourse site I host.) I was lucky enough to interview with Andy Vandervell, but I didn’t make the cut. A month or so later I got an offer for my current job at the OpenSSL Foundation and figured I would never think about PostHog again.
But in the course of applying for PostHog I started using it on my sites. (I naturally wrote about that too.) In order to help out clients of my (not very large) consulting business, I added PostHog to sites I built for them too. After the OpenSSL Foundation re-launched our site in January on Webflow. I got sick of using their almost useless analytics and shifted to PostHog to monitor traffic. So I still follow PostHog on the various places people follow companies they are interested in.
When this job listing popped up on LinkedIn, I realized the thing I most enjoy about my current job is writing blog posts about highly technical topics, posting them on Facebook, and getting comments from not-so-technical friends and family members about how they now understand, for example, post-quantum cryptography. (I’ve also heard from a university professor who teaches cryptography that he uses my posts to introduce topics to his students.) Full-time technical blog post writing about software I use anyway seems like a great job.
What makes for a good technical blog post?
Start with a goal for the post and an audience. A fairly common post type is convincing potential customers (the audience) to try out a new feature (the goal). In my opinion, the only effective and reliable way to do that is via the power of story. This doesn’t mean writing the next great epic, but just a simple story connecting a problem your audience might have to the solution the post introduces.
Say you want to introduce “Encrypted Client Hello”. A lot of people won’t know that that is and another portion of people will sorta vaguely know what it is because they sat through a talk about ECH a few years ago or something. Start with whatever motived the feature to be made in the first place. (For ECH, it encrypts the one part of the SSL/TLS connection that isn’t encrypted: the client hello.) Talk about who might most benefit from the feature. (People who are worried about censorship, especially living under repressive governments.) Explain how the feature works in simple, easily-grokked language. (ECH is like sending a letter to a clearing house that reposts it to the final destination.) Appeal to the reader to try the new feature. (ECH works better when it permeates the ecosystem. Even if you don’t personally worry about third parties seeing what servers you visit, using ECH helps everyone who is worried.)
It really helps to know your audience. The ECH post I did for the the Library blog goes much deeper and assumes a lot more background than the Foundation blog, which is aimed at a more general audience. But I still made sure to tell a story that I hope resonates.
The payload of the post might be a mini-tutorial to get started. But that can often be left on another page where it’s going to get updated as the software gets updated. Links to documentation, source code, examples, etc. help readers, search engines and AI crawlers find more details about the feature. If you’ve done your job well in the first part of the post, the story you’ve told will motivate the reader to find out more. All that is needed is a pointer to the next step.
I find getting fact-checks form an LLM helps avoid the most embarrassing errors. Human reviewers usually find gaps in the story or places I’m unclear. An interesting picture or illustration engages people to even start reading. You do need to share in the usual places so that your audience finds the post. Don’t forget to look at traffic data to make sure it’s performing the way you hope it will. (It’s sorta depressing to watch session recordings of people reading a paragraph or two before switching another page. if that keeps happening, it’s a good sign the post isn’t nailing it’s story.) Finally, the post can be linked to from future posts and added to existing posts.
In summary, good technical blog posts tell a story that motivates an audience to move to a desired outcome.