Editorial strategy

Emphasize hands-on experiences and stories

In the post How Safari Ruined My Tuesday on Fly.io, the author hooks the post on a personal story (as exemplified in the title).

Sentences like “In the whole of the internet, there’s only one, lonely Stack Overflow thread talking about this issue affecting mobile Safari” and “This was an annoyingly difficult issue to debug. Safari’s web inspector will tell you the computed property of the elements is pointer-events: auto, but it’s lying. Elements won’t respond to click events. Bad times. It’s like living with IE6 again” demonstrate the actual lived experience of software development. In other words, it’s relatable.

Include humor

In the post API Tokens: A Tedious Survey on Fly.io, the author prefaces the post with a sales pitch but does so in a humorous way, making it more palatable:

“We’re Fly.io. This post isn’t about Fly.io, but you have to hear about us anyways, because my blog, my rules. Our users ship us Docker containers and we transmute them into Firecracker microvms, which we host on our own hardware around the world. With a working Dockerfile, getting up and running will take you less than 10 minutes.”

The in-depth value of the post (it’s 39 minutes long) likely also makes the pitch more palatable.

Examples are a great opportunity for humor. In the post What is an A/B Test?, the Netflix Engineering blog authors write “Let’s say — this is a hypothetical! — we want to learn if a new product experience that flips all of the boxart upside down in the TV UI is good for our members” and includes an image of all the boxart on the Netflix home screen upside down.

Assume readers are knowledgeable

In the post API Tokens: A Tedious Survey on Fly.io, the author includes a sub-hed that reads “Let’s Take Passwords Off The Table” and the section beneath is only two sentences long:

“It’s 2021 and so I don’t need to tell you that having your API pass a username and password through HTTP basic authentication is a bad idea. Your tokens should look large and random, whatever they are.”

Writing like this signals to devs that the author is writing at their level. Though there’s some risk of excluding people who don’t know these facts, it pulls in readers who’d otherwise bounce, readers who’d think this post is for beginners if they saw things explained that they already knew.

Similarly, in the post How We Got to LiveView on Fly.io, the author asks the reader if they remember a fact from software development’s past:

“Do you remember when Ruby on Rails was first released? I do. Rails was also a revolution. It hit on the idea of using an expressive language and a few well-chosen, unifying abstractions to drastically simplify development. It’s hard to remember what CRUD app development was like before Rails, because the framework has been so influential.”

Again, readers who weren’t around or who weren’t near the Ruby on Rails release might feel alienated. But the risk is worth the gain because it proves–and this is something that needs to be proven multiple times in every post–that this post is by devs, for devs.

That said, there’s a balance to strike. On the Uber Engineering blog, in the post CRISP: Critical Path Analysis for Microservice Architectures, the article includes a background section with two, weighty sub-sections explaining information necessary to understand the rest of the post. We’ll have to understand our audience on an article-by-article basis to know when to explain and when to assume.

You can elide some of this problem by including a list of concepts the reader will need to already understand to understand the post, as Using Drizzle and React to write DApp frontends on the LogRocket blog does.

Move the development world forward with research

In the post Kangaroo: A new flash cache optimized for tiny objects, the Facebook engineering blog summarizes a paper that won Best Paper award at the 2021 Symposium on Operating Systems Principles (SOSP) conference (a paper the Facebook engineering team and Carnegie Mellon University partnered on). The post is, by nature, original; it’s hard to skip because the learnings will, theoretically, push the industry forward.

Present lessons learned

The post Autonomous testing of services at scale on Facebook Engineering ends with the concluding sub-hed “Deployment and lessons learned.” This section, six paragraphs long, notably doesn’t summarize the preceding post (like many conclusions do) but instead gathers up the lessons learned from the story retold in the post. The conclusion goes through these lessons point by point, e.g. “Second, we learned that…” and “Third, we noticed that…” and without any fluff.

As another example, the post Build AI-powered customer conversations in Google Maps and Search with Google’s Business Messages on the Google Developers blog ends with a “Final thoughts” section, which the author uses to summarize the preceding post and leave the reader with a departing CTA and a “I can’t wait to see what you build!”

Criticize erroneous approaches

One way to demonstrate your knowledge is to not only recommend one approach but to recommend against another approach. In the post A linear programming approach for optimizing features in ML models on Facebook Engineering, for instance, the author calls a different approach “naive”:

“A naive solution would be to just start picking the features with the most gain (teal squares) until you are out of capacity. However, you might not be making the best use of your resources if you just prioritize the gain.”

Being critical of other approaches shows you know the world of possible solutions, not just the one you’re writing about. Criticism demonstrates, too, that you have the intelligence and wisdom to know many approaches but choose one.

Be transparent about struggles and results

In the post Migrating Facebook to MySQL 8.0 on Facebook Engineering, the author is transparent about their struggles, writing sentences like

• “Our last major version upgrade, to MySQL 5.6, took more than a year to roll out.”
• “Version 5.6 was approaching end of life…”
• “When we initially scoped out the project, it was clear that moving to 8.0 would be even more difficult than migrating to 5.6 or MyRocks.”
• “It took a couple of years to complete porting all of these features.”

And in the post Improving HDFS I/O Utilization for Efficiency, Uber Engineering writes the good: “The Good: ~90% of the disks have an average IO utilization of less than 6%.” and the bad: “The Bad: the tail end of disk IO utilization can be as high as more than 15%, which is more than 5 times greater than the average disk IO utilization. Even though these disks are a fraction of the entire disk pool, they represent thousands of drives.”

And in the post How we’re making Dropbox data centers 100% carbon neutral, Dropbox Tech uses the sub-hed “Results (so far)” as a place to both share their results and signal that there’s more to come. We shouldn’t pretend that any technical effort is one-and-done.

Build and share

Developers are builders. One great way to frame and structure a post is to build something and then write about why you built it and the experiences you had along the way. This type of post is also a great way to talk about your product without coming across as self-promotional.

In the post Build your next video application on Cloudflare on the Cloudflare blog, for example, the author explains that “Historically, building video applications has been very difficult” but then explains how “Cloudflare Stream abstracts all the difficult parts away, so you can build custom video and streaming applications easily.”

This is all in the first paragraph, so there’s no sneakiness about this post being product focused. Instead, the focus is a step-by-step explanation of how they used the product to do something devs too would like to do.

Take (and cite) inspiration from the community

In the post Why don’t people like PHP? on the LogRocket blog, the author highlights a Twitter thread that inspired the post. Citations like these prove we’re involved in the community and in the discourse, and validate that devs are asking questions we can answer.

At the same time, if you’re wading into a contentious topic, be prepared for your readers to have opinions. In the same post, readers commented that it sounded like the author didn’t do their research, writing that “I don’t understand the point of this article or what it is you’re trying to accomplish. A LOT more research should have been done.”

Balance depth and compactness

The Fly.io blog focuses on two extremes of the length-spectrum, primarily writing either “FYI” posts that take less than five minutes to read or long blog posts that take 20-30 minutes or more.

• Example: FYI: Phoenix drops webpack and npm for esbuild takes three minutes to read.
• Example: API Tokens: A Tedious Survey takes 39 minutes to read.

The average FYI post takes three minutes and the average regular post takes 21.5 minutes.

Another strategy to find this balance is to write multi-part posts. In a series of posts on decision-making at Netflix, the Netflix Engineering blog writes a three-minute intro post (Decision Making at Netflix) and, as of November 18, with more to come, has written four more posts in this series.

Include plenty of code snippets, diagrams, graphs, and gifs

In a single post, How We Got to LiveView on Fly.io, the author includes 12 graphic elements, including code snippets and gifs of UIs in action. In the post Autonomous testing of services at scale on the Facebook Engineering blog, the author includes architectural diagrams. In the post Superpack: Pushing the limits of compression in Facebook’s mobile apps on Facebook Engineering, the author includes bar graphs.

Enable readers to get started ASAP

Don’t wait for the end of a post to put a CTA. In the post Build AI-powered customer conversations in Google Maps and Search with Google’s Business Messages on the Google Developers blog, the author writes an introductory section, a definition/explanation section, and then jumps into a “How do I get started?” section.

Developers aren’t allergic to CTAs; they’re allergic to overtly promotional CTAs. If you’re giving them the option to play with something you just got them intrigued in, a CTA might be great to include.

Also, make the CTAs dev-specific. In the post Build your next video application on Cloudflare on the Cloudflare blog, the authors end with “Check out the source code and get started building your own video application today!” It links out to GitHub, not a landing page or other marketing material.

Highlight tools used

Tools are a signal that a blog post is relevant to a given reader. In the posts Building Uber’s Fulfillment Platform for Planet-Scale using Google Cloud Spanner, the Uber Engineering blog authors cite two tools and in the post Real-Time Exactly-Once Ad Event Processing with Apache Flink, Kafka, and Pinot, they mention three.

Highlight job openings

A good technical post explains why and how a development effort was made. Doing so effectively serves multiple purposes, but an underrated one is attracting new hires. Demonstrating the fact that our team takes on complex, interesting technical challenges, and uses innovative or interesting or otherwise effective methods to address them, is attractive to potential applicants.

In the post Why we built a custom Rust library for Capture, for example, Dropbox Tech ends the post with a “We’re hiring!” section and asks readers “Do you love Rust? Do you want to grow as an engineer? Dropbox is hiring!”