The Role of Technical Tutorials in Developer Marketing

Technical content can make or break your developer marketing program. Tutorials are a critical piece of the content mix that your developer audience relies on. Karl Hughes from Draft.dev offers his thoughts on how to get them right.

Karl Hughes

Draft.dev

Best Practices

Successful developer marketing programs require great technical content. Tutorials are a critical piece of the content puzzle and often the hardest to get right. The stakes are high - they can be a dealbreaker for developers evaluating or working within your ecosystem.

With that in mind, we’ve invited Karl Hughes from Draft.dev to share his thoughts on creating winning tutorials for your content mix.

-------

Tutorials are one of the most common types of content in developer marketing and developer relations. In the past year, our team at Draft.dev has written over 1100 technical blog posts for clients, 32% of which have been tutorials.

Developer marketing is unique among the many flavors of B2B marketing in that it relies on this kind of hands-on content at all stages of the marketing funnel. In fact, for some of our clients, tutorials are the only kind of content they publish for developers.

So in this piece, I’d like to share a bit more about the role tutorials play in developer marketing. I’ll compare them to other forms of technical content, and share specific examples of how we’re seeing leaders in the field use tutorials at each stage of their developer marketing funnels. Finally, I’ll offer a few tips for producing and maintaining tutorials based on what we’ve learned creating hundreds of them for our clients each year.

What is a Tutorial?

If you’re new to developer marketing, you might not be familiar with the term, so let’s start here:

A tutorial is a piece of content that walks a user through all the tasks required to accomplish a specific goal.

Tutorials can be written, recorded audio or video, streamed live, or interactive, but I’ll focus primarily on written tutorials today. When created for software developers, tutorials will almost always include screenshots, code samples, and references to documentation.

Tutorials vs. Documentation

Tutorials typically go beyond documentation by weaving together docs with a specific use case.

For example, we wrote a multi-part tutorial for Amadeus that shows developers how to build a hotel booking application. While the writer referenced their hotel booking API docs, they had to fill in a lot of gaps to set up the environment, build the user interface, and store state across multiple steps.

Tutorials should not replace good documentation, but they should certainly augment it. We typically see tutorials being used as a way to showcase real-world use cases for APIs that are already fairly well-documented.

Tutorials vs. Guides

Finally, it’s important to distinguish between tutorials and the type of technical content we call “guides.”

Guides are higher-level explanations of a concept. For example, this guide to Docker Networking we wrote last year shares code samples and lots of details about how Docker networking works, but it isn’t walking users through a specific solution step-by-step.

Guides are an important part of developer marketing too, but they serve a different purpose than tutorials. Where tutorials help developers solve very specific problems or showcase uses, guides help them understand more general best practices or tradeoffs for various solutions.

Why Write Tutorials?

With the definitions out of the way, let’s get to the heart of things. What role do tutorials play in a comprehensive developer marketing strategy?

I’d like to highlight five specific ways our clients use tutorials. None of these is mutually exclusive and there is overlap between them, but hopefully, this gives you a starting point if you’re trying to figure out the best way to use tutorials in your marketing efforts.

1. Answering Search Intent

I spent ten years building software, but without Google, I’m nearly worthless at writing code. Software developers are notoriously good at Googling solutions to their problems, so memes like this are only partly tongue-in-cheek:

This is good news for content marketers who understand keyword research tools like Ahrefs. While not a panacea, I’ve seen lots of our clients generate traffic and attract users by creating tutorials that answer development-specific search queries.

For example, consider the keyword, “elasticsearch kubernetes.” Ahrefs tells us that at least 400 people per month search for this specific keyword and that it’s not too difficult to rank for. There are probably also dozens of long-tail variations of this keyword combination, so if you’re Elasticsearch (or a competitor), you might want to rank for this term.

Developers who are looking for information on this topic are almost certainly trying to figure out how to run Elasticsearch on Kubernetes. And as you’d expect, the top results include Elastic’s documentation and a short tutorial on the topic.

So, if you’re Elastic’s marketing team, it’s important to have content that captures this search term. It ensures that when users look for this information, they’ll find you first. Similarly, if you’re a competitor or complimentary product, you may want to have content that shows up in the top 10 results as well.

2. Showcasing Use Cases

Writing keyword-focused content is typically good for attracting search traffic, but it isn’t really the type of thing that gets shared widely on social media. This is where creative and interesting use cases for your product might be a better choice.

One of the developer tools companies doing the best job with tutorials on Reddit and Hacker News is Fly.io. They do a great job building little demo apps that showcase creative uses for their edge hosting platform and distributing those pieces on developer communities.

For example, this piece on building a turn-based game in Elixir is really good.

I can bet that very few developers are actually searching for tutorials about building distributed, turn-based games in Elixir, but this piece gathered hundreds of upvotes and comments on Hacker News, so I’m sure it brought in plenty of pageviews and at least a few users.

While depending solely on viral content is a risky marketing strategy, it can be a great part of a successful content mix. Our most successful clients intersperse interesting tutorials with keyword-focused ones to drive both short-term buzz on social and long-term awareness via search engines.

3. Highlighting Integrations

A lot of developer tools rely heavily on integrations. For example, Redpanda is a streaming data platform that sits between an application and a database, so the only way to use it is as part of your data stack.

Redpanda has created a lot of content highlighting the various integrations they support, including tutorials like this one on integrating ClickHouse.

Pieces like this serve two purposes:

First, they help developers who are considering Redpanda see that they support their existing infrastructure. As a developer, I can tell you there’s nothing worse than finding a great tool, validating it in a test project, and then finding that it won’t really work in your production environment because it doesn’t support some existing piece of architecture.

Second, they give marketers great assets to cross-promote with integration partners. If I worked for ClickHouse, I’d be happy to help share a piece that showcases my product, even if it’s hosted on another company’s blog.

4. Helping Your Sales Team

For many of the companies we support, developers are stakeholders in a multi-party sale. Other companies have both a developer persona (who likely wants to trial the product) and an enterprise persona (who will need to book a call). In sales-focused companies like either of these, developer marketing collateral isn’t necessarily focused on attracting developers as prospects, but rather preventing developers from becoming a roadblock to a deal.

For example, InfluxDB is a time series database with both bottom-up and top-down marketing channels. Like any database, developers will need to integrate it into their applications, but they also support enterprise sales to larger companies.

To show developers that they support their chosen languages and frameworks, InfluxDB is creating a growing library of tutorials that their sales team can send to any prospects who are afraid developers might stand in the way of a sale.

This shows developers that their product works in almost any existing environment, and it also helps when an existing user needs help setting up InfluxDB in a new environment.

5. Supporting Customer Support

Finally, tutorials are great for improving your customer support and developer experience.

I’ve already pointed out that developers are Google wizards, and when we have an issue, we turn to Google or Stack Overflow before contacting support. So, the more published tutorials you have that solve common problems developers might face, the more likely they will get their answers faster.

This kind of content also helps lighten the load on your support team. It’s much easier for them to send a complete tutorial than to repeatedly answer the same question from developers who hit an error.

One example of a company that’s starting to create this kind of support content is WordPress. In this piece, they lay out some of the common errors developers face when using the WordPress API and show them how to fix each. While community content on this topic may exist, WordPress having content on their site ensures that developers get the most up-to-date and correct information on the topic.

While many companies have a customer support division independent of marketing, the two functions are very tightly related. 89% of business customers are more likely to make a purchase after a positive support interaction, so it’s relatively easy to draw a line between better support and more growth.

What Makes a Good Tutorial?

While there are many use cases for tutorials in developer marketing, the best tutorials created for any purpose share a few common features. Here are the four elements we stress to clients and writers:

You Need Subject Matter Expertise

One of the reasons many marketing teams don’t produce tutorials is that they require access to subject matter experts (ie: software developers). Good developer tutorials need to include working code and a repository of the completed project, so it’s just not something your marketing team can fake.

What’s more, each tutorial you do might require a different subject matter expert.

For example, an expert Ruby developer can offer unique insights into a Ruby tutorial that they may not be able to in Python. Similarly, a frontend developer might be able to create a great React tutorial but have no idea where to start with a Kubernetes one.

Many of our clients use a mix of internal and external subject matter experts. For example, their Developer Relations team may be able to write pieces on Python and Java, but they’ll bring in community members or an external agency like Draft.dev to work on pieces in Golang and PHP.

Provide the Right Amount of Context for the Intended Audience

In general, the more knowledge and experience the writer has with the topic, the better their tutorials will be, but not if they gloss over too many details. On the other hand, some expert-level tutorials shouldn’t enumerate every single step as the audience is likely to have already implemented basics like an environment or framework set up.

Tutorials should be calibrated to the intended reader, and it’s important to remember that not every developer implementing your tool will be an experienced senior engineer. So, be sure to create tutorials at different levels of complexity and link back to more basic tutorials if you need to skip steps in a more advanced one.

Focus on the ***Why, Not Just the How***

In my appearance on the Stack Overflow podcast last year, I pointed out that one thing separating decent tutorials from great ones is explaining the why.

For example, a passage like this is a typical way to introduce a tutorial:

In this tutorial, I’ll show you how to use Postgres’ JSON fields to store unstructured data in a relational database.

Not bad, but it also doesn’t tell me why I might want to store unstructured data in a relational database. Senior devs might not need this, but more junior ones are probably curious, so you could at least add some context and a source to help readers at all levels:

While there has been debate around the value of NoSQL databases, there are times when you may want to blend structured and unstructured data in a single store. It could simplify things if relational data would require complicated `JOINS` or help you avoid messy transformations on external data. So, in this tutorial, I’ll show you how to use Postgres’ JSON fields to store unstructured data in a relational database.

The more you can explain why throughout your tutorials, the more accessible and interesting the content will be.

Keep Them Up to Date

Finally, once you manage to create tutorials, you have the neverending challenge of keeping them up-to-date.

One of the only constants in software development is that things are constantly changing. Software written as little as 10 years ago might be hopelessly impossible to fix, so you’ll probably have to revisit or rewrite your tutorials every 1-3 years. This problem is especially pronounced for early-stage startups or new product launches that are changing quickly.

While it would be nice if you could simply update version numbers in existing tutorials and hit refresh, it’s almost always more complicated than that. Most of our clients end up doing complete rewrites using the previous piece as a loose template. It’s a challenge, but having tutorials with deprecated, unsupported, or insecure information on your site is an even bigger problem.

Conclusion

Reliable, correct, and useful technical content is one of the most integral parts of developer marketing for many organizations, and tutorials play an especially important role. Whether you’re trying to attract new users through SEO or social media, or you’re trying to ensure your existing users are adequately supported, you will find a good case for tutorials centered around your product.

Have any advice that you’d like to add? Questions about tutorials? Connect with me on Twitter or Linkedin to continue the conversation.