Publishing blogs with Github, CircleCI, and Google Analytics

Introduction / Background

At Nextdoor, we treat our engineering blog like an independent engineering project. A handful of engineers, forming a committee (co-op), manage the process of publishing a weekly blog entry. The tools that we use to draft a blog, review the entry, and publish to the world are all centered around our main users, engineers. Our goal is to make writing as frictionless as possible for our engineering team so that they can focus on the most important aspect of it — sharing the awesome work we do to help make neighborhoods stronger and safer.

How we craft a blog post

We publish one blog post every week. We have over 50 engineers and we take turns writing blog posts, which is similar to our oncall rotation — except that you write a blog post once a year, rather than once every 3 months. :)

Engineers do things in the engineering way. We write posts using Markdown and we manage posts using Github Enterprise, where we have an engblog.git repo. In the repo, each blog post has a separate directory, where there is a Markdown file for post contents, a meta.ymal file for meta data, and a subdirectory for images.

Oftentimes, more than one engineer works on the same blog post. We’re already used to working together on the same code base, mostly for plain text files. Therefore, we have no problem dealing with Markdown files, which are plain text files, too.

We work on a new feature branch for each blog post. We create a pull request and add reviewers on Github Enterprise for “code review” before publishing a blog post. We typically include our peer engineers as reviewers, as well as people from the communications team, who are surprisingly happy with such “code review” process on Github Enterprise!

Here’s how it looks like to “code review” a blog post on Github Enterprise:

Continuous integration

The published blog would appear on WordPress, so the content still needs to get exported from GHE to WordPress. This is where continuous integration comes in. For regular projects, CI is used to run tests, publish artifacts, etc. For engblog, we leverage CircleCI to create a WordPress draft.

This script walks through our directory structure looking for meta.yaml file and parses out the information required to publish a WordPress blog. Future improvements include automatically uploading images and creating gists from code snippets, but for now we do this manually.

The script that publishes the blog to WordPress is here.

Promoting content

Once the content is reviewed and published on our blog site, we use various channels to promote our content.

Internal promotion

• First, we announce the new blog entry in our internal company wide forum. The message contains a brief summary of the blog and encourages our colleagues to read it and share it on various social channels. Also, this helps to raise awareness of the engineering blog and nudge our fellow engineers to be part of the movement.
• Additionally, we have a one page description of the blog that we print out and post in our bathrooms. Surprisingly, this has been a very effective way to spread the word about the blog to the entire company. For example, our CEO, Nirav, mentioned it in one of our all-hands.

External promotion

• The members of the engineering blog co-op share the blog through social channels including Facebook, Twitter, LinkedIn, and Hacker News to kickstart the virality. We carefully analyze the effectiveness of each channel and continue to optimize how we promote.

Data analysis

We want to know our audience — understand what people like to read, when they choose to comment, and why certain posts are more viral than others. Google Analytics is an excellent, off the shelf, free tool we leverage to track out progress.

We meet once a week to take a look at how the most recent blogs have performed. We also look at former blogs that continue to have new readers. This means that the content is widely relevant and has good SEO.

Conclusion

When engineers start writing, good things happen.

One of our core values as a company is to communicate openly. With engineering blogging, just like with open source software, we aim to share the tools and the knowledge we have about current technology with the rest of the community.

We also believe that writing about the great work we do every day promotes a better engineering culture. Not only does it help spread the word about Nextdoor engineering, but writing the blog also allows engineers to feel greater ownership of their work. It’s also great to receive feedback from other developers in the community and gain new perspectives on the problems we tackle. We started to put more emphasis on our engineering blog a few months ago, and it’s amazing how much content we have created so far. Of course, we have so much more to share, so stay tuned and subscribe for more updates.

Also, if you’re interested in joining us, we’re hiring!