An Engineer’s Guide to Running an Engineering Blog
Hi, I’m Sekhar, and I’m a Software Engineer at AdHawk, where I work on the Red Panda Team building our B2B products for the flooring industry. I’ve been an engineer for about five years now and at AdHawk for coming up on four of those. I wanted to write about how we built a simple and sustainable system for blogging as an engineering team. I hope our experiences help other organizations that may want to start a similar technical blog on their respective teams.
A Brief History of the AdHawk Engineering Blog
At AdHawk, we’ve gone through a couple of iterations of an engineering blog. Having joined the company as the second web developer and ninth employee back in June of 2016, I’ve been through the rollercoaster of seed-stage, pre-profit startup life. Getting bandwidth to focus on a project without direct technical and business impact was difficult to say the least the first few years.
Sporadically, my Senior Engineer at the time Ian Ker-Seymer and I would write posts, including these first two posts on TypeScript and RSpec Matchers, and we set up a simple Medium blog here that we still use to this day. I then wrote Trello tickets right into our sprint board workflow at the time. I assigned a blog post ticket per sprint to one of the other few engineers on the team, including one that became our iOS Engineer Diego Watanabe’s post on iOS for Javascript Developers.
From here, it became difficult completing our engineering blog tasks, especially as business priorities came up, and it was inevitably the last priority on everyone’s mind. The writing tasks needed to move out of the sprint board. Even with a separate Trello board though, there were just too few engineers (<6 employees), to have a critical mass to write consistently. Without a clear business or recruiting reason to have our engineers writing regularly, it was near impossible. This system died after that one post by Diego.
In the interim in 2017 and 2018, Ian and I wrote a few posts, and Ian even covered a talk with an embedded video of him speaking at an Atlanta Ruby meetup called GraphQL for Your Rails App. Our at the time newer teammate Pat Sparrow wrote our most popular post by claps (628 as of this writing!), Designing Services with dry-rb. While we averaged a post every three months or so, mostly from this small core group, something needed to change if we wanted to take our blog to the next level.
Engineering Blog Relaunch
After years of thinking about it and wanting to build a sustainable system for blogging, in March of this year I linked up with my new VP of Engineering Justin Jones, my longtime colleague Ian (now Director of Engineering), and our Lead Engineer Pat. I spoke about the structure I wanted to try out and we all brainstormed a bunch of potential blog post ideas to fill up a GitHub board so potential writers would be inspired to write about a topic. By this time we had over two dozen teammates across the Product Team, so we were in a very different place as a company and department.
Starting April 2nd, 2019, when I published a blog post called “Hanami: Simplified Models through Repositories and ROM,” our AdHawk Engineering Blog has relaunched. We’ve had consistent biweekly posts, about topics ranging from technical to cultural to personal and more. I have led this relaunch and have evangelized the engineering blog throughout, both internally and externally. I sell this as an at most 10% time commitment during a sprint (~2–4 hours per writer, within just one two week development cycle) for the writing contributor.
About a month in after we started getting buzz from other engineers and I got inbound questions from many colleagues, I gave a lunch & learn talk over a Zoom call to everyone on the Product Team about the why & how of blogging on our team. Every two weeks, timed with our sprint cycles, I’m working with a writer to publish a post on our team (unless I’m writing myself). Interest and awareness has increased dramatically and I’m super pleased with our progress this year and consistency compared to the first three-plus years at AdHawk.
How We Run Our Engineering Blog Today
Our current development sprints as engineers run from Thursday to Wednesday, over a two week period, and we time our blog efforts with that. I personally maintain a GitHub project board with various potential topics, and potential nominees to write about specific topics. I ensure our posts are tracked by status from backlog to in progress to published. For the subsequent two sprints, I have a writer picked out for each, and they’re made aware and invited to my recurring calendar events, one for each week of the sprint.
Speaking of which, my biggest tip on getting an engineering blog going is this: set up recurring calendar events! I have a biweekly beginning-of-sprint Thursday afternoon event for 15 minutes for just me, that’s called “AdHawk: Engineering Blog Planning.” I ensure we have our two writers picked out for the coming month’s worth of work, and I groom the GitHub project board.
The middle full week of our sprint I have a recurring Wednesday afternoon event for an hour called “Edit Engineering Blog Post Draft, Share Draft in Slack,” which I always invite the committed writer to as a first meeting. If the time needs to be moved, the writer or I can move it, and I always block that hour off biweekly.
In the calendar event description for this first event, I wrote, “Can edit your blog post with you as it’s in progress, whether it’s an outline or even just an idea. Let’s ensure we meet just to keep the momentum going on writing. Feel free to start on it in the meantime!” I’ve found these meetings incredibly useful to keep the consistency high for the blog and split the writing task up into manageable chunks for engineers.
At the end of the sprint, on Wednesday again I have a biweekly morning recurring meeting called “Finalize and Publish Engineering Blog Post,” which again the writer is always invited to for the sprint in which they’ve committed to blogging. By this point, a solid draft should have been written coming into the meeting, ideally within Medium itself (which has great drafting features). We read the post out loud as we edit to catch errors, tone, and style, and we try to fine-tune any wording, add images to the post, play with layout, and more.
After publishing the post at the end of the meeting, we share the post in our #p-engineering-blog Slack channel, where I generally tag a marketing point-of-contact to let them know they can share this post on social media and other outlets. I ensure the writer is added to our publication in Medium (where I’m an admin), so we can receive the post.
When publishing, I ensure we don’t check the curated content/allow the post to be pay-walled checkbox. I also have the writer hit “Add to Publication” from the published post dropdown menu so their post can make it to our company blog. This seems like a good system to allow posts to be from engineers personally, but also be a part of our blogging efforts as an engineering team.
The writer will generally post a link to their published post in #p-general, our Product Team-wide general Slack channel, and rake in all the emoji reactions from their colleagues. From there, I encourage the writer to share on any social media outlets they’re on, and personally since I use LinkedIn I will share or reshare my colleague’s Medium or LinkedIn post about the engineering blog there and add a snippet of my own.
The next day, Thursday, is the beginning of our next sprint, and I’ll check in around my 15 minute calendar event and plan out the subsequent two sprints, and the cycle starts all over again. The writer for this sprint was already picked out two weeks ago and invited to the calendar events, so I’ll usually shoot them a direct message on Slack to check in and ensure they can still meet their writing commitment. Overall, this system has continued pretty well with minor process improvements since we started doing it in April.
—
That’s pretty much a full summary of how we’ve evolved as a team in relation to writing our engineering blog here at AdHawk. As you can imagine, because we’ve gone from ~4 engineers to over 25 people strong over the past four years, our writing efforts and consistency have changed dramatically. Medium has been a solid system for blogging for us and while there are many future ideas for improving and scaling this blog, I think we’re in a great place for the coming year.
I feel quite content with where we are as a team and showcasing our efforts both externally and internally, and I know every engineer who’s participated has enjoyed getting their story out there. I often have to push my writers to sell themselves and their accomplishments. Writing for the engineering blog has an enormous amount of benefits for every person involved as well as for our organization.
If you have any questions about running an engineering blog or experiences you want to share with it from your team, feel free to comment. I would love to hear what your team is up to!
