It’s nice having you back for the final part of this series presenting you my last six tips on how to write better tutorials. If you haven’t read the previous articles, you can catch up here with part 1 and part 2.
Take a deep breath in and a deep breath out—on we go!
1. Let readers know about your tutorial’s completion time
We all have so much to do and the time on our hands is limited, which makes it difficult to fit all our plans into one day. That’s why you should provide your readers with an estimation of how long it will take them to complete your tutorial.
This estimation helps readers to decide how they’re going to approach your tutorial. Are they able to tackle all in one session or do they need to plan an hour of work for the next five days? Furthermore, if you’ve split your article into several parts, your readers can’t see the length of the whole thing and thus, can’t estimate the completion time by themselves.
The ideal place for your time estimation is at the top of your article, next to the metadata (category, author, publishing date). Make sure your users see this info at a glance and don’t have to read through too much text.
2. Inform your readers about updates
I already wrote about the importance of displaying your article’s publishing date. Your readers should know if they’re looking at something outdated.
Also remember, your old article might still be relevant to some of your users.
If you have a popular tutorial, update it every once in a while, or write a new one using current technologies.
Let your readers know about your updated tutorial! You could add the updated_at info next to the publishing date. Additionally, add some details about what you updated before your tutorial text starts. To make sure your users see this in a second, write in an italic or bold font.
Something like this:
Update 10/10/2018: rewrote some functions to make use of PHP 7’s new spaceship operator
If it’s worth writing a new article from scratch for your tutorial, don’t delete the old one—some users may still find it useful! Also, make use of this tutorial’s fame and place a link to your new version at the top of it.
This could look something like this:
Note: I wrote a new version of this tutorial in which I use Angular 4 instead of Angular 2. Read it here (don’t forget to add the link 😉 )
Your readers will love you for writing good, updated content while embracing the old if necessary!
3. Test your code and instructions
Before you hit the publish button of your CMS, make sure your tutorial is correct! Therefore, take a break and leave it for at least 24 hours to get some distance. Afterward, work through your tutorial step by step like a reader would. See if you forgot adding relevant information, or an essential line of code.
The best way to test your tutorial is by having a guinea pig of course. If there’s someone you can send the tutorial for testing: do it!
Often we are stuck in a certain way of thinking, and another person may have helpful input on your content.
Don’t have a partner in crime? Reach out to other writers and propose a deal in which you read and test each other’s text and code.
Having errors in your tutorials once in a while is no drama—you’re human after all. Imagine though, those errors pile up, and thus your users aren’t able to complete your tutorial. Sounds counterproductive, doesn’t it?
4. Write recaps of long parts
It can prove helpful to recap junks of your tutorial because especially long sections can be overwhelming for your readers. By repeating the steps, you took before, you refresh your readers’ memories.
The easiest way to recap is by providing a list at the end of a section. In long tutorials, put the recap before a subheadline introduces the reader to the next topic. When your tutorial is short, place your recap at the end of it.
Imagine something like this:
Let’s recap:
- You learned about routing in Laravel
- We set up the basic structure of our project
- We entered all necessary information into our environment file
- You learned how to create different environments (remember to use the local one for development)
- …
Now the user has the opportunity to see if he still remembers everything listed. If not, he can immediately go back and reread certain parts. Do you see how useful this can be?
5. Provide the full code to download
You usually split up the code you present in your tutorial, and thus should provide the whole project to download. This can, for example, be on your server or on Github.
It’s always a bit different if you only see code snippets or the whole code base. Your readers can even learn more when they have the opportunity to look at every file in your project. Maybe they messed something up in a file you didn’t even touch in your tutorial. If they are beginners, it can be hard for them to find the error without help.
You see where this is going :). Give users access to the full code so they can compare your project files with theirs which helps them to find the place where things went wrong.
You never know about potential problems your readers might run
6. Collect questions for a follow-up post or FAQ section
Do your readers ask the same questions over and over again? Do you receive tons of queries regarding your tutorial?
Well, then you should think about writing a follow-up post or including an FAQ section in your article.
In a follow-up post, you can grab those most asked questions and answer them in an instructional style. This can turn out to be a tutorial for your tutorial—maybe this sounds bad, but it isn’t. Those questions mustn’t arise because of your writing or the quality of your tutorial. Often they go deeper into the matter and are more advanced.
If there’s not too much to explain you can also edit your original tutorial and add your explanations there.
Don’t fancy writing a new post? Append an FAQ section at the end of your article!
By keeping this sections up to date, your readers’ questions will get less and less repetitive. Although, for some reason, a few people aren’t willing to read and still ask the same questions over and over again. With your FAQs in place, all you need to do is to refer to them.
In the long run, this strategy can prove beneficial for you! You update your tutorial on a regular basis (which search engines like). Additionally, you provide your readers with helpful and valuable information. As a side effect, you’ll position yourself as a go-to-source and a sympathetic person.
18 tips on how to write better tutorials
Writing this series was quite enjoyable for me! I hope I was able to show you something new or something you haven’t thought about before. Also, I’m thinking about creating a short recap with all my tips from this series for you to download. If you’re in my newsletter list or are following me on Twitter, I’ll let you know when this guide is ready.
Are there any tips you think are essential which I didn’t include in this series? Let me know, and I’ll also add it to the upcoming recap (of course I will give you credits for it).
No responses yet