A few years ago, I made the transition from being a full-time software engineer to writing technical content for a living. Since then, the company I started (Draft.dev) has written thousands of blog posts for over 150 different developer tools companies, and well over 1000 of those posts have been tutorials.
The reason for this is simple. While there’s plenty of value in higher-level thought leadership and competitor comparisons, it’s rare to meet a developer marketing or relations team that doesn’t want to publish more examples of how to use their product.
Honestly, I get it. Tutorials have a lot of utility. They can be used for search engine visibility, to showcase specific use cases for the product, to overcome objections from technical stakeholders, to supplement documentation and minimize support requests, and to improve your developer activation rate.
But tutorials are also time-consuming and difficult to create. Unlike less technical types of content, it’s nearly impossible for a marketing person to write something like this in-depth tutorial on how to use Bazel we wrote for a client a couple years ago.
So, most developer marketing teams must lean on internal engineers or freelancers to help them create tutorials. Assuming you can get the resources to do this, your next challenge is to help engineers, who may not be the strongest writers in the world, create content that’s approachable, readable, and accomplishes the business goals you have for it.
In this piece, I’d like to share a few tips for writing better tutorials. Whether you’re a software engineer who’s been asked to write something for your company’s blog or documentation, or you’re a non-technical marketing person who’s trying to help their contributors improve their skills, this advice should help.
1. Start with the “Why”
As I pointed out on the Stack Overflow podcast recently, good tutorials show readers how to accomplish something, but great tutorials also explain the why.
Smart developers who are reading your tutorial aren’t robots. They are likely reading this tutorial to learn something or get closer to solving a problem, but if you don’t offer context along the way, they won’t be able to creatively apply the lessons they’re learning to their own work.
So, start your tutorial by sharing why this particular topic is important, but remember to continue explaining why each step is important along the way.
2. Know your audience
Typically, my top tip to all new writers, as knowing your audience definitely applies to writing tutorials.
If you’re explaining a nuanced topic to senior-level software engineers, you can skip some of the really straightforward steps or reference another source (I don’t need to be told how to install NPM every time I read a new tutorial!).
But, if your intended audience is broader or includes beginners, it’s important not to gloss over the little details. Typically, the worse sin is under-explaining, but you’ll have to decide which way to lean based on your goals.
3. Use code samples and screenshots
As a reader follows along with your tutorial, they’ll likely want to copy code directly from your post, so be sure to use embedded code samples and not screenshots for any code snippets.
On the other hand, you should use screenshots to show readers the results of any working code throughout the tutorial.
For example, this tutorial we wrote for a client uses both screenshots and code samples throughout.
Finally, while code samples and screenshots are a good start, it’s also a good idea to include a link to your completed project on GitHub. This allows readers to clone the repo and get a complete working version of the code, but it also allows readers to submit fixes in case your tutorial has any bugs.
And, while we’re on the topic of bugs…
4. Test, test, test!
There’s nothing more frustrating than following a tutorial online and then realizing that it simply doesn’t work. While it’s hard to keep tutorials up to date because tooling and compatibility is always changing, the least you can do is test that the whole thing works while you’re writing it.
During our quality control process at Draft.dev, we always have a second engineer test any code or demo apps, but if you don’t have the resources for that, at least make sure the writer does a final test on the whole tutorial before publishing.
5. Include rich media if possible
Another great way to make your tutorials stand out is to use rich media like video, interactive demos, or embedded IDEs.
Video is great because it also serves as another distribution channel (many developers prefer to learn via video), but it’s also time-consuming to produce.
Embedding your entire demo application used to be impossible, but newer tools like CodePen allow you to easily drop working code samples into a blog post. This can be helpful if you want users to interact with or customize your code directly in the browser, and it serves as another distribution channel as well.
Speaking of distribution channels…
6. Make time to promote each tutorial
One of the biggest mistakes our clients make is publishing content and not reserving adequate time to promote it. I wrote a whole blog post on this topic back when I first started the company, and it’s still one of the staples we send to clients during onboarding.
Besides the obvious promotional channels (your social media, internal newsletters, and company Slack channels), there are a number of creative ideas I’ve gathered from clients over the years, including:
- Syndicating content on Dev.to, Medium, and Hashnode
- Pitching the piece to developer-focused newsletters
- Running paid advertising campaigns to the tutorial
- Sharing on appropriate subreddits and Hacker News
- Sharing with outside community Slack channels
- Creating video snippets to share on Linkedin, Twitter, Instagram, or TikTok
And don’t think that, once you’ve shared a tutorial, you’re done with it. You can usually reshare it every few months, as most of the content on these channels is pretty transient.
Conclusion
Writing tutorials is a great way to emphasize a developer tool’s features, showcase important integrations, and decrease support requests. And, even if you’ve written about similar topics before, it’s okay to showcase different solutions to the same problem.
Finally, if you’re looking for more tips for creating technical content or tutorials, we’ve got longer guides on both on the Draft.dev blog. I’m also happy to connect with you and answer any questions on Linkedin or Twitter.
Teresa Garanhel
