How to write better Tutorials – Part 2

Finally: the second part of the series ‘How to write better tutorials’. In the previous part, we talked about the necessity of structuring your content, adding images and professionally looking code snippets to your tutorials amongst other things. Make sure you read the first part here.

And now, let’s get straight to the point!

1. Display the publication date

It became quite fashionable to hide the posted_at info in articles and tutorials, which adds up for your evergreen pieces covering topics that are always relevant. But when it comes to tutorials, you should show your readers when you wrote the content, and ideally when you last updated it.

Let’s say your tutorial teaches something about PHP and you used the newest version at the time of writing. After a couple of months or a year, there sure is a newer PHP version available. That’s why it’s important to let your readers know when you created your content, so they know instantly if this seems outdated.

Technology evolves so quickly which makes it hard to keep everything up to date. But this doesn’t mean your tutorial isn’t relevant anymore! Many developers have to work with old versions of programming languages or technologies, for example, when they’re working on an older project. So your article still might be useful to them.

Now you’re probably saying: Heya Sarah if I display the posted_at date my page misses out on clicks and traffic!
And yes, you’re right. But: If a user visits your tutorial and immediately closes his browser tab because he sees outdated content, you’ll gain nothing from it! Yes, you’ll get a user visiting your page, but you’ll also get a higher bounce rate for this page. The longer a user stays on your page, the better Google thinks about it. High Bounce Rates might be an indicator of outdated, irrelevant or lousy content and search engines prefer the opposite.

2. Tell your readers what they’ll gain

Right at the start, you should let your users know what you’re about to teach and what the results will be. You can write about two forms of results:

1. The actual result, the product. So maybe this tutorial is about setting up a routing system in a particular language.
2. The skills your readers acquire. After completing your tutorial, your readers should have learned something, let’s say, how to plan an effective routing system.

I can imagine some cases where it’s unnecessary to point this out, but it’s good advice to at least think about writing it down and decide whether this is something your reader should be informed about.

3. List the tools and services you’re going to use

Also right at the beginning of your tutorial is the ideal place to list all the apps, services, and tools your reader needs ready for usage to complete your tutorial.

It might frustrate your readers if you tell them about a tool they need not until somewhere in the middle of your article. Your readers’ flow gets disrupted, and they must pause the tutorial to hunt up tools they require before continuing. Also, maybe your users are against using a particular tool, let’s say a chargeable service because they aren’t ready for this commitment yet. Consequently, if they don’t know about this right from the start all the work they invest in your tutorial might be in vain.

So, just create a simple list at the beginning of your article in which you list all tools you’re going to use in your tutorial with a note where to get them. Let your readers prepare!

4. Link to other resources for further reading

It’s probably hard to cover everything in your tutorial thoroughly, but luckily there are others who provide that content. You should go ahead and link to these other articles and present your readers with more learning materials.

Some may think, linking to other sites should be avoided because you’re going to ‘lose’ readers, meaning they click the link and leave your page. Firstly, you can always set the link’s target to _blank, so it opens in another browser tab. Secondly, relying on other writers is a good thing! You may gain new connections and collaboration partners that way. Write him a message that you have written a tutorial about topic X which includes a technology that the other author has covered in one of his articles, and that you have posted a link to this article. Maybe he even shares your tutorial on social media – who knows!

Providing your users with all the necessary information is the main reason to include external sources in your tutorials.

5. Use comments throughout your code

When you talk about general stuff, methods, and principles, your text sure is the right place for this. But if you explain or point out what happens where throughout your code, then there is no better place than putting this information directly into your snippet.

Let’s say you wrote a recursive function because you’re tutorial obviously is about recursion for beginners. In your text, you explain what recursion is, what it’s good for and how it works. But in your code example, you point out what’s happening, like ‘If x is true, we call this function again’.
By writing such explanations directly into your text, you make it harder for your users to follow your descriptions.

Make reading your text and code easier by knowing where to write what.

6. Keep the user engaged and make it fun

Learning should be fun and engaging! Almost everybody says that, right? But you’d search for ages to find the foolproof advice out there which adds more fun to your content. It depends on the chosen topic and your writing style!

Write by using your own voice. You want to avoid writing extra fancy words, and you’ll recognize it’s much easier if you keep your writing more like your talking. This also adds some extra authenticity to your articles, because you and your style are unique and this is something you want to show off!

If you’re the type who likes to write more seriously, that’s fine too. As I said, be yourself and avoid forcing it.
Your readers shouldn’t lie on the floor laughing anyway. They are here to learn something!

Keep your readers attentive – using subheadlines, paragraphs (see Part 1 of this series), and a rich vocabulary also helps you to achieve this.
Plus, consider a tutorial about a fun project! Why write the thousandth article about ‘How to programme a simple Todo List with programming language X’? I’m sure you can come up with something simple but yet effective!

We’re almost finished

You made it through the second part of how to write better tutorials! There’s one part left, where I tell you about my last six tips on this topic. If you haven’t read the first part yet, make sure you check it out if you want to here. 

Have you ever written a tutorial? If yes, what was the trickiest part and what did you like the most about it?