Where should my content live? Docs or blog?

13 May 2023 in Business

It’s 4pm on Thursday and you’ve just wrapped up an awesome piece of content that you’ve been thinking about for over a month. You finally had time to sit down and build a demo and write down how you did it so that others can follow along too.

Then you hear the age old question:

Are you planning to publish this on our blog or in the documentation?

The question hits you like a ton of bricks. Not this again. You just wanted to write. To teach. Who cares where it’s published? Just publish it so that others can learn!

The thing is, where you publish your content is important. Let's take a look at when you'd choose to publish on your blog, and when to contribute to the documentation.

Choose the Blog

There are a couple of instances where content should definitely go on your blog rather than in your documentation:

It’s an announcement rather than something educational
It’s a fun extra that’s not really core to your business (e.g. “managing your infrastructure with Terraform”, where you just happen to deploy your product)
Niche but interesting technical content (e.g. how we diagnosed network performance issues on $cloud)
It’s something that you want to publish now, but not maintain forever. Publishing on a blog means that it has a published_at date. People don’t expect a blog post from 2017 to be accurate, and are a lot more forgiving. Some examples of when this is useful:
- Collaborations with other companies
- Using X with your product (where X is the flavour of the month, such as AI)
- Using X with Y, where newer versions make the instructions invalid
Anything that contains an opinion. This is typically your thought-leadership type content

If your content doesn’t fit in to any of the above buckets, you may choose to publish it on your blog anyway. This is typically the case when:

Your blog has much better SEO than your docs and you want people to find the content
The author’s personal style does not fit the rest of your documentation, but the content benefits from having a unique style
You’re trying to tell a story rather than educate someone. Blog posts can skip a lot of the prerequisites for a project and assume the reader knows enough to get started.

Choose the docs

When we publish documentation, we commit to it being accurate forever. We need to regularly revisit pages to ensure that the content is accurate for the current version (and potentially older versions too). It’s no longer a snapshot of a point in time. It’s a living thing that grows with your product.

It’s an easy decision to put things in the docs for me if any of the following are true:

You need to maintain the content indefinitely
It’s focused purely on the how rather than the why
It’s a step-by-step tutorial on how to achieve something with your product
It’s a reference document, such as an API specification or configuration reference
There are multiple code samples showing how to achieve a single task

You might also choose to put the content in the docs if:

The content is maintained by multiple people, follows standards and has a consistent tone of voice
It’s something that you need to send to customers. Being in the docs add’s an “official” feeling to the content

Help me decide

If you’re still not sure where to put your content, put in on your blog. It’s the lowest friction way to get started, and having the content somewhere is generally better than not having it at all.

Writing precise, organised, complete documentation takes time and effort. Writing a blog post takes time and effort too, but less so. People are more forgiving when it comes to transient content.

Once published, watch your analytics. If you see a blog post receiving consistent traffic, you should officially adopt the content and work it in to your documentation (at which point you’ll have the fun “what about our SEO” conversation where everyone’s too scared to move the content).

In summary

Use the blog for time-limited content. Use the docs for evergreen
Explain why on the blog, and how in the docs
Authors have a unique style on the blog. Content is uniform in the docs
If you’re sharing ideas, use the blog. If you’re educating, use the docs.
Finally, if there’s a risk the content won’t get published at all, just use the blog. It’s easier to move from the blog to the docs than it is to remove something from the docs later.