This blog post is the final post of the Mixmax 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!
