Great Technical Tutorials Address the "Why" and "How"
As tech advances, the content we produce about it should also evolve: demo videos, blogs, social posts — and yes, even tutorials.
As straightforward as they may seem, tutorials hold a world of potential for building trust with your audience of developers. But finding people who know how to write a tutorial that consists of more than just a series of steps copied and pasted from somewhere on the internet? Feels impossible.
I was recently invited to chat about technical tutorials on an episode of The Stack Overflow Podcast. I spoke to hosts Ben Popper and Ryan Donovan about what makes tutorial-style content stand out and why it’s risky to hire just any writer to create it.
The Difference Between a Good Tutorial and a Great Tutorial
If you’re trying to speak to software engineers with your content, it has to hit upon what they really care about: why they should take a certain approach. (They often already know a lot of the how.)
Yet, most of the online content you’ll find about software tools comes in the form of dry listicles or step-by-step tutorials that don’t offer valuable context to developers who are often trying to solve complex problems.
Ideally, the person writing your tutorials should understand:
- Why the reader is completing these steps — and why now
- Why this technology is interesting
- Why alternatives aren’t as good for this use case
You can’t address these whys with simple step-by-step directions.
After reading a great tutorial draft, you should be able to answer “yes” to the question: Will the reader have a full understanding of the applications of this tool?
Finding Writers Who Get It
If you want to grow and reach more developers, you need to do a lot of writing — whether it’s for documentation, FAQs, or to establish your brand’s public-facing presence.
Content marketing is just one piece of that picture, but it should be treated as an entirely separate entity if you want your content to truly speak to your audience.
Coming up with technical content ideas is one challenge, and finding writers who can turn those topics into effective pieces is another, even more difficult, one.
Especially if you outsource technical content creation, you may struggle to find someone who can write about the deeper lessons underneath an engineering task — because they probably aren’t entrenched in the field themselves.
Furthermore, you can’t always tell from a pitch whether a writer knows their stuff. You’re taking a risk when you hire a technical writer who has some freelance experience in the industry but doesn’t spend their days writing code.
And that’s the big problem we’re solving for startups here at Draft.dev — writing content that’s for developers by developers.
Low-Code Solutions Also Have a Why
The proliferation of low-code software tools might reduce the demand for tutorials. But there’s also more opportunity for SaaS businesses to revamp the standard tutorial and include the bigger reasons your customers or clients would be doing a task in the first place.
A simple example: “How to Set Up a Child Theme in WordPress” vs. “Why You Should Set Up a Child Theme in WordPress.” The latter would explain how updates to your website won’t override your future changes, which is important for someone trying to maintain their own site, while the former leaves the reader wondering if they need to do it at all.
With more complex tools and processes, there are also reasons for everything we do as developers. Even if a tool doesn’t require customized code, there are still lots of use cases and different approaches or opinions you could include in a tutorial to make it widely applicable.
Pro Tip: To come up with better angles for a basic tutorial, consult your list of keywords and try to discover the intent behind each search. What would the person really be looking to discover? What kinds of lingering questions might they have after reading a basic tutorial?
The Future of Developer Content Marketing
As you’re likely aware, SaaS businesses are getting a lot of funding right now. That’s great for the industry overall, but it also means there are even more competing software tools out there.
To set your brand apart, you should be creating a core base of valuable technical content.
A sharp developer who’s trying to get better at their craft needs to know more than what a simple “How-To” post can cover, so they’ll be looking for a tutorial that was written by someone who successfully connected the task at hand to the reason they’d be doing it.
_____________________________________________________________________
Listen to the episode to hear more about the need for more in-depth tutorials.
By Karl Hughes
Karl is a former startup CTO and the founder of Draft.dev. He writes about technical blogging and content management.
Build a Blog that Software Developers Will Read
The Technical Content Manager’s Playbook is a collection of resources you can use to manage a high-quality, technical blog:
- A template for creating content briefs
- An Airtable publishing calendar
- A technical blogging style guide