How to Write an Engineering Blog Post

SHARE ON

This blog post is the final post of theMixmax 2016 Advent Calendar. The previous post on
December 11th was about
a lightweight alternative to automated integration tests.

When talking with friends about these last twelve days
posts, the most common reaction hasn’t been to any individual post but rather the concept itself:
“how do you have so much stuff to write about?” The glib answer would have been “well, Mixmax does a
lot!” But (while that’s true :), some team members actually expressed the same worry when we first
talked about the idea—even though they are all brilliant engineers, they didn’t immediately see
what they had to contribute. In response, we came up with some strategies that everyone could use to
write a post. And in the spirit of giving with which we began
the series, we’ll finish by sharing these strategies with you.

Talk about what you’ve built

The first and easiest strategy is to talk about what you’ve built. This is easy for Mixmax engineers
because all of our projects begin with an architecture proposal and/or implementation spec, and we
default to open-sourcing new infrastructure. So,
when it comes to writing about this work, we basically already have a draft! We just have to take the
spec or README, add a little bit of background on the technologies involved at the beginning, and add
a little bit about our use case at the end.

My colleague Trey’s post about
securing server-side requests with our
rewt library is a great example of this strategy. The bulk of
the post is almost a direct copy of the “usage” part of rewt’s README. To make it a post, he just had
to describe how and why we built rewt, by talking about different approaches to securing server-to-server
communication and JSON web tokens at the beginning, and then giving an example of how we use rewt to
sign and verify HTTP requests at the end.

Talk about what you’ve learned

The next strategy for writing an engineering blog post is to talk about what you’ve learned. This
is closely related to talking what you’ve built—what makes these posts different is talking
about the process, rather than the results. You can also talk about what you’ve learned integrating
with technology you didn’t build, for instance 3rd-party APIs. If you’ve found gaps in their
documentation—or even outright bugs—that’s a blog post waiting to happen.

My colleague Cameron’s post about
integrating with the Gmail Pub/Sub API
is a great example of this strategy. All he had to do to write a post was collect the various bugs he
had found and support them with links to the API’s documentation.

My post about requiring Node built-ins with Webpack
is another example. Here the topic was less that Webpack was buggy than that its documentation wasn’t
clear. But even when the problem’s on the author’s end (PICNIC),
documenting missteps will help other developers avoid similar pitfalls.

Talk about what you think

A theme connecting the strategies we’ve talked about so far is that when it comes to writing a post,
you don’t have to make stuff up—you can just write about what you know. But the posts we’ve
talked about haven’t just been “facts”—how something works or doesn’t work. If they were, they’d
be rather dry and even unsatisfying. What makes a great post is the author’s view on why something
ought to work a certain way. And this leads us to our final strategy for writing an engineering blog
post: talk about what you think.

Your opinions are valuable (no, really). Engineers are always looking for new ideas and new ways to
organize their thoughts. And what may seem like old hat to you may be completely new to someone else
since there’s so much to learn and technology is ever-changing.

These two facts explain the endless parade of React tutorials and ES6 explainers. And they meant that
it was totally fine for us to publish our own contribution
to the latter category. What makes my colleague Chuy’s post particularly interesting isn’t his code
samples, it’s his perspective on why he chose to discuss these APIs:

While some of the new ES6 features can be considered syntax sugar, they also open the door for much
more concise and understandable code.

We all may have to read something multiple times before we get it. Your perspective on a “familiar”
topic may be what finally clicks for someone else.

You too can write an engineering blog post

After sharing these tips with my friend, the one who’d originally asked about how the advent calendar
was possible, he still demurred, saying that his company’s legal department would never let him
publish what he was working on. And to this I say—start small! Document what you’ve built, if
only internally, to make things easier for the next developer. Try your hand at writing a spec, and
maybe you’ll prove your ideas worthy of implementation. Write a post about how your company’s
already-public APIs can be used to build cool things.

Or, if you’d like to default to building new tech, open-sourcing it, and talking about it, you can
come work at Mixmax. 🙂 Join us!

SHARE ON

Written By

Jeff Wear

Jeff Wear

From Your Friends At