How we blog

How we blog

People have been asking me lately where to blog, and how we reason about how we do it. So instead of copy-pasting my answer around in different Slack groups, I thought I would blog about it here. For there's nothing like blogging about blogging, is there?

What do we blog

I have regularly been blogging since I started working as a developer advocate at Sanity in August, nearly half a year ago. Broadly, our blog efforts fall into three categories:

1. Guest posts on high-quality publications

2. Blogging about product features, news, and new releases

3. Tutorials combining Sanity with technology more or less in vogue

In the first category, we have posts such as the one presenting Sanity’s image pipeline on CSS-Tricks, or our article about “Strategies For Headless Projects With Structured Content Management Systems” on Smashing Magazine. To more general posts for FreeCodeCamp, such as “How to conditionally build an object in JavaScript with ES6”. While such posts don't necessarily give you lots of traffic and conversion, they have been vital for us in establishing a voice of expertise. Moreover, it has to be said, a lot of work has gone into writing them.

Especially the article on strategies for projects involving structured content has been critical for formulating some ideas that have been swirling in our minds for quite a while. Writing for high profile publication like Smashing Magazine also forces you to do some diligence. It forces a different pace than your off the cuff post about familiar topics.

The second and the third category are pretty much given. There is a lot of surface to cover on Sanity, tons of functionality, and all those subtle, nifty things that are useful for all sorts of developers. Did you know that you can live-edit a cloud hosted document in your favourite editor as easily as sanity documents create --id myDocId --watch --replace? No? Well now you do!

There's just so much you can do on landing pages, and you can't really expect people to do a close reading of your documentation. So we blog about tricks you can make the CLI do, what you can do with GROQ, or the awesome video plugin we made for Mux. We also want to tell people that Sanity is really well suited for popular front-end frameworks and give some clues on how to get started. Our tutorial on how to make a blog with Next.js is unsurprisingly one of the most popular posts on our blog.

How do we blog

Of course, our blogging happens in our instance of Sanity. I must admit that I often do some initial drafting in a markdown editor, mainly out of old habit. Doing the writing in Sanity’s editor is excellent "dogfooding" though. We often run pre-release versions of the editor so wrinting becomes a part of the QA process. Once the text is ready, we hit publish, and it's on our site, and present in both our RSS and JSON feeds.

An essential part of the process is the review. It's not just code that goes through peer-review. At Sanity HQ we have made a Slack channel called #marketing-review, where I post a preview link to the post after I've done the primary spell-check. I always get some useful feedback and corrections.

As Sanity uses Portable Text, we made a tiny script that exports the blog posts to Markdown, ready to be syndicated in markdown based blog platforms. Which takes us to the next section.

Where do we blog

A couple of years ago, Medium gained lots of traction, mainly because of its clean editor and polished design. Now though the honeymoon is over, and people realize that they miss a lot of recogniztion from search engines by putting their content elsewhere. In other words, it's terrible for Search Engine Optimization aka SEO. Tempting as those claps 👏 on Medium might be, in the long run hosting your content under your own domain seems to be the best strategy. Provided that you also please the Google algorithm by having a fast, user-friendly site.

That's why we always make sure to publish our blog posts on sanity.io first. Once we have done that we typically syndicate those blog posts to the wonderful dev.to site, and to Medium where we submit it to the HackerNoon publication (which interestingly also moving off of Medium soon). It's important to make sure that these places set a canonical url tag, telling Google and other search engines that the duplicated content has a home elsewhere and is legit.

The canonical URL interface on dev.to

On dev.to it's relatively easy (bless their hearts!). It also lets you automatically import content via RSS, which is nice, but I prefer using our markdown export script. On Medium you have to find the super subtle “Import a story” button.

The import story button on Medium

You give it your URL, and it fetches your content and sets the original URL as canonical. Note that you can't change this later, so you'll have to be sure that you got it right. I tend to have a lot of code snippets, which in Medium tend to get totally borked, so I often have to go through the text and fix those manually.

Once I have published, I'll compose a text for social media often with some illustration or animated GIF if there's some functionality we want to visualize. This message is also peer-reviewed before it goes out on Twitter, Facebook, and LinkedIn. I usually don't repeat these messages, which I am reconsidering. Especially on Twitter you're easy to miss in the stream.

Why do we blog

Blogging is ubiquitous, and pretty much everyone attempting to get the word out does it. That also unfortunately means that there's a lot of noise. So we are dependent on social media, link list sites, and organic search to be heard. There's a high bar for your words to really make difference. This blog post seems to support that notion. When figuring out the economics of * cough *, content production, you find yourself wondering about quality vs. quantity or insight vs. listicle if you will. When running the numbers on this it would be tempting to hire out and go for volume.

But in promoting Sanity, we're not just trying to sell a product. We're also trying to talk about how we fit into a changing landscape of software literacies and digital production. The way we see it, we make it a lot easier for developers to use content as a pure digital resource, to deploy relational data structures and customize editing experiences. We fit into optimal workflows for interdisciplinary teams where a clean separation of concerns lets you bootstrap projects in parallell. Even though our technology is persuasive in itself, changing how people reason about their craft and how they go about it doesn't happen overnight.

So blogging is not “just marketing” for us; it is also a great way to think about your product, and the problems we're trying to solve. It is in itself rewardning to put into writing all the delightful and useful things we experience Sanity can do for you. It's like Merlin Mann & John Gruber pointed out almost ten years ago (their talk is worth the listen by the way): great blogging is recognized by your obsession on a topic combined by your ability to develop a voice. We've nailed the former, and we dare to hope that we sometimes achieve the latter. So should you.

Install Sanity:
npm install -g @sanity/cli && sanity init|