Things to Keep in Mind When Building an Engineering Blog
Updated: Mar 10
This blog post was originally published on March 5, 2018. It has since been updated with new content.
Back when I was responsible for running the company blog, I was intent on getting content from as many teams as possible—not least of all the engineering team.
At some tech companies, it isn’t unusual to see a main blog and a few niche blogs run by teams within the company (most notably design and engineering). The company blog was too small to split up, and that alone meant that we could be creative and experiment with different types of content. Nonetheless, a lot of the challenges that I've experienced sourcing content from internal writers also applies to organizations with team-based blogs.
In this post, I'll share some of the lessons I've learned when working with engineers on original blog posts, and how this can help your team maximize its blog efforts.
What Makes Engineering Blog Posts Successful
When I asked many of my colleagues which engineering blogs they liked, I got answers like Code as Craft and the Netflix Engineering blog. Engineering blogs are popular among developers for many reasons:
They show readers what in-house engineering teams are actually working on. Engineering posts help peers understand what a particular individual or team within a much larger organization actually works on, keeping sales and marketing to an absolute minimum. These posts tell us about an engineering team’s philosophy as well as their stack.
But they're also educational. Well-written blog posts offer unique perspectives and different solutions to old problems. They help the reader learn about a specific topic and technology, and walk readers through how that topic/technology is applied to help the team work through a challenge. Readers should learn something new.
Whenever I get pitches from our engineers, regardless of the topic, the first question I ask myself is, "Why should a reader care?" Readers don't just want to look at a blog post and say, "Cool, Company X did this thing...." and that's it. At the very least, they want to understand:
Why was this approach taken?
What went into deciding on that approach?
What is this [topic/software/etc] that was chosen and why?
What lessons came out of it?
I always come back to "Why should readers care?" whenever I am editing, because blog posts must provide some value to the end reader. Engineering blog posts are not just about "show and tell"; they're how your engineering teams shares knowledge with peers across the wider tech community. And engineering blog posts provide value to the engineers writing them; they increase an engineer's profile and they give the engineer the chance to share what they've worked on. And for engineering managers, they're a great way of attracting new candidates.
Setting Up An Engineering Blog: What To Expect
There are many benefits to publishing engineering blog posts, but what are the challenges? Looking at any litany of engineering blogs, and you'll notice two types of engineering blogs:
Blogs that run out of steam early on. A lot of content is published in the early stages, but the cadence becomes unsustainable, with new posts published infrequently.
Blogs that publish regularly. They may not publish every week, but they've found a sustainable cadence (one or two a month, for example) that indicates an editorial process—and maybe a primary blog owner—in place.
Based on what I've seen from managing the company blog, here's what engineering blogs need to be successful and sustainable:
1. Buy in from engineers. To get buy-in, clearly communicate how the blog benefits engineers to individual contributors and engineering leaders (and assure them it won’t conflict with their main responsibilities). Without buy-in or express interest, a blog sounds like an extra work assignment to engineers with a lot on their plate already. Instead of announcing to the company that I was looking for engineers to write posts, I reached out directly to individual contributors that were conference speakers, published on their personal blogs, or were working on interesting projects. I told them why this content was important to us and wanted to build meaningful relationships with them. I positioned myself as a partner in their growth. (The best part about this? People started reaching out to me directly once engineers told their colleagues about their positive experience writing for the blog.) 2. A primary owner. Without a primary owner, a blog runs the risk of not having dedicated resources to keep it sustained over the long haul. If you’re trying to get engineering posts on the main company blog, it’s likely that someone on marketing will be the person managing the blog. But if your engineering team wants to establish a team blog, someone will need to be tasked with managing it. Managing a blog entails overseeing the editorial calendar, editing posts, sourcing new content (or looking through submissions), and working across teams to promote these posts. This person will also be responsible for creating, maintaining, and updating blog guidelines and reporting. Ideally, this person will be dedicated to the blog full time or will have content management as one of their core responsibilities.
3. A regular publishing cadence. Whether you have ten blog posts ready to go or just one with a few coming down the pike, you want to establish a sustainable publishing cadence. In the beginning, this might amount to 1 or 2 posts a month, but only consider increasing the cadence when you’ve determined how many posts you can successfully publish without straining bandwidth on your team.
4. Ongoing conversations for a healthy content pipeline. In my experience, for every five conversations I have with an engineer, I will usually get one draft within a month. Oftentimes months lapse between initial conversation and published post. The reason for this is simple: engineers aren’t in-house writers. They are taking on writing a blog post in addition to their existing responsibilities and priorities. It is not uncommon to see engineers put a post on hold because of competing priorities. The more conversations you have, the greater the odds that you’ll find enough content to help you sustain your cadence. (At the time of writing this in 2018, I had four engineering posts in the pipeline, and I was still reaching out to engineers for new content whenever possible!)
5. Flexibility. Being flexible is key, for all of the reasons outlined in #4, and because flexibility demonstrates empathy for your colleagues. To keep things on track, you want to give engineers enough space to work on a post without feeling nagged, but you also want to make sure you follow up appropriately. Once an engineer has expressed interest in writing a post, I ask them what amount of time makes the most sense for turning in a draft. If they tell me within 2 weeks, I usually give them 3-4 weeks. The week before the agreed-upon deadline I’ll send them a friendly reminder on Slack and ask them if they still have time to turn in a draft within a week. If they do, great! But if not, I tell them I’ll revisit the topic with them in a few weeks time, and actually set a reminder for myself on my calendar to follow up with them. Sometimes, I leave it open-ended and tell engineers to ping me directly when they are ready to work on a post. This is a great way to promote good, working relationships with colleagues. 6. Partner with marketing. There are definitely engineering teams that promote blog posts via team-run social media accounts. But the best part about working at a larger organization is…there’s already a team that does this work at scale: marketing! Reach out to colleagues in marketing and let them know what you’re team is working on. Ask them for opportunities to promote these posts on official company social media properties, email newsletters, and other channels.
Additionally, ask them about their martech (marketing tech) stack and what they use for web analytics. If you care about tracking and reporting on your blog (and you should; how else will you know whether readers can find your content or whether anyone is actually reading it), you should ask marketing for pointers about what tools they use, how to set up tracking plans, and how to create reports and dashboards.
7. Encourage open dialogue.
One last, but not least, component that should not be overlooked is engaging with readers. At my company, we have an open comments section on every blog post which I moderate. Whenever we get questions from readers, I forward those to engineers, and I encourage engineers to answer questions (offering to review their comments beforehand if they want someone to check for things like tone, but it's often not necessary). If your blog doesn't have an open comments section, let readers know where they can go to continue the conversation. Can they reach out to the author via social media, for example? A shared inbox/repo/etc where they can submit feedback? You might not always get people reaching out—and that's OK!—but it's always nice to let folks know that they can communicate with someone directly.
In conclusion, engineering blog posts allow in-house engineering teams to share knowledge and best practices, demonstrate expertise and allow engineers to speak to what they're working on directly. They are opportunities for giving back to the wider community as well as engaging with them, and are often a great way to find a team's next hire. To be successful, engineering blog posts should communicate a clear value to the reader. Teams need buy in from the engineering org, a primary owner for all things blog related, a regular publishing cadence, ongoing conversations, flexibility, cross-functional communication, and open dialogue with readers to get the most out of their blog efforts. With a bit of planning, your engineering team can get on the road to producing high-quality, engaging posts that your peers will appreciate!
Like this post? Purchase The Developer's Guide to Content Creation for more content-related tips and exercises. (Get the Teams version to distribute to up to 10 members of your engineering or developer relations team.)