Writing Good Software Development Tutorials
Let's say you've spent countless hours building a software development tool, open source project or an API and now it's time to write a tutorial for your users. Good tutorials increase user engagement, user retention and reduce support queries. So, what makes a successful tutorial?
A Clear Introduction
An introduction should tell the reader what they will get out of the tutorial, what the learning objectives are and what the prerequisites are.
Learning Objectives
Learning objectives outline what the user will learn. They should be brief, clear, specific statements of what learners will know by the end of the tutorial. Objectives are particularly useful when the tutorial teaches multiple concepts and you refer back to them throughout the tutorial.
A good example of effective learning objectives can be found in the guides of the MDN learning area: An example of a learning objective on the MDN website
Prerequisites
Being clear on what the prerequisites are is key. Throughout the tutorial, you shouldn't assume the reader has any knowledge unless it is stated in the prerequisites. Is your tutorial for a Python library? Then state the user should know Python. Is it a tutorial for a web framework? Then state that the user should know the basics of how the web works. These types of prerequisites can seem too obvious to mention but they should be included to help your readers. This React guide is a great example of prerequisites being done well. An example of clear prerequisites
Put Yourself in the Reader's Shoes
It may seem obvious but always think about the tutorial from the users perspective. When you have experience using a tool it's easy to forget what it's like to use the tool for the first time. You should start from fundamentals at every stage of the tutorial and only build on knowledge contained in the prerequisites or the tutorial itself. Prerequisites help to mitigate this problem but this type of assumed knowledge can creep into technical tutorials in subtle ways. The most common example of this is using technical terms or acronyms without clearly explaining what they are.
Explain Why
At every step of the tutorial, you should explain why you're doing what you're doing. Telling a user to write some code without explaining why you're doing it isn't going to teach them how to use the code in the future or how to approach future problems. Explaining why you're doing something can mean that you need to explain the context and background of a step.
Use Explicit Language
You should use explicit language so the tutorial is very clear and without ambiguity. Your reader should have a clear and concise understanding at each step of the tutorial.
Explicit language helps to lower the amount of complicated information the reader is processing, so they can focus on the point of the tutorial. Using explicit language also helps non-native speakers.
Some tips to make your tutorial's language as clear as possible:
- Try to keep sentences short and simple
- Use common words whenever possible
- Use an active voice
- Eliminate extra nouns and filler words
Don't be a Language Nerd
Reinforce Topics
Once you've taught your audience something, you should reinforce it. This can be done in a few ways. The simplest is to refer back to the learning objectives or repeat what you've just taught them in a summary at the end of each step.
One of the most effective ways to reinforce learning is by providing tasks to complete at the end of each section. The task should be something that uses what the audience has just learnt. For example, if you've taught them how to create a button for a user interface get them to create another button. To keep it interesting and reinforce things further, try to adapt each task slightly. Maybe the buttons position should change or it could be a different size.
A task at the end of a tutorial
Engage with Critical Feedback
Your most unhappy customers are your greatest source of learning - Bill Gates
If somebody gives you feedback you should pay attention to it and try to act on it. A tutorial isn't done once it's published - it can always be improved!
It's always tempting to blame your audience if they don't understand something or they complain that something doesn't work but this is an opportunity to improve the tutorial.
Speaking of feedback, please let me know what you think of this guide! Hopefully it has helped you write your next user engaging tutorial.
Thanks for reading!
If you found this article useful and can spare a dollar, I’d appreciate the support.
I believe in privacy and I don’t run ads. For analytics, I use the open-source platform Plausible.
