The following passage is quoted from: https://diataxis.fr/tutorials/#writing-a-good-tutorial
Allow the user to learn. In the beginning, we only learn anything by doing - it’s how we learn to talk, or walk.
Give your learner things to do, through which they can learn. Only your pupil can learn. Sadly, however much you desire
it, you will not be able to learn for your pupil. You cannot make them learn. All you can do is make it so they can
learn.
As you lead the pupil through the steps you have devised, have them use the tools and perform the operations they’ll
need to become familiar with, building up from the simplest ones at the start to more complex ones.
Your job is to get the learner started, not to turn them into an expert. Don’t ever be embarrassed to start right at
the beginning: a user can skim rapidly over what’s unnecessary, but if they need something and it’s not there, you risk
losing them altogether. It’s also perfectly acceptable if what you get the beginner to do is not the way an experienced
person would, or even if it’s not the ‘correct’ way - a tutorial for beginners is not the same thing as a manual for
best practice.
The point of a tutorial is to help your learner set out safely on their journey, not to get them to a final destination.
The only reason not to lower the threshold is because you decide that you don’t want the responsibility of teaching
beginners at below a certain level, or you judge that a certain level of skill is a reasonable prerequisite for using
the product at all.
It’s important to allow the learner to form an idea of what they will achieve right from the start. As well as
helping to set expectations, it allows them to see themselves building towards the completed goal as they work.
Surprising them with the result at the end will diminish, not augment, the value of what they achieve. It’s very
enjoyable to reveal impressive conclusions with a flourish, but you should save that for your magic tricks and novels.
Providing the picture the learner needs in a tutorial can be as simple as informing them at the outset: In this
tutorial you will build a simple website using Django and deploy it using Docker. Along the way you will use a cloud
storage service for handling media files, and will configure your application to use it.
One of your jobs as a tutor is to inspire the beginner’s confidence. Confidence can only be built up layer by layer,
but is easily shaken. It helps to maintain a friendly tone, as does consistent use of language, and a logical
progression through the material. However, the single most important requirement is that what you ask the beginner to
do must work. The learner needs to see that when they follow your directions, they will attain the results you
promise.
It’s hard work to create a reliable experience, but that is what you must aspire to in creating a tutorial.
Your learner is probably doing new and strange things that they don't understand. Don't make them do too many before
they see a result from their actions. As far as possible, the effect of every action should be clear to them as soon as
possible. The relation of cause and effect should be evident. Finally, each result should be something that the user
can see as meaningful.
Every step the learner follows should produce a comprehensible result, however small.
Unless you're very lucky, the users of your tutorial will have different levels of skill and understanding. They might
also be using different tools and operating systems and you can't rely on them having the same resources or
environment.
This makes repeatable reliability extremely hard to achieve, and yet, your tutorial should work for all users, every
time.
You have no alternative but to test your tutorials regularly to make sure that they still work as expected.
Tutorials are composed of concrete steps, not abstract discussion. Be specific and particular, about actions and
outcomes.
Resist the temptation to introduce abstraction. All learning proceeds from the particular and concrete to the general
and abstract. It's later, after a beginner has encountered multiple concrete examples that they are ready to see a
pattern in them and seek an abstract account of what is happening - until that time, requiring the learner to handle
levels of abstraction before they have even had a chance to grasp the concrete is confusing and places unnecessary
burdens on them.
It's hard to resist this temptation, because once we have grasped something, we rely on the power of abstraction
to frame it to ourselves - and that's how we want to frame it to others. But it's simply not how learning or
successful teaching works.
If the learner doesn't need an explanation in order to complete the tutorial, don't explain.
For example, it's enough to say something like: We're using HTTPS because it's more secure. There is a place
for extended discussion and explanation of HTTPS, but not in a tutorial. Sometimes, even that much explanation is
more than required.
It can seem problematic that we are asking a user to do things, without much explanation why. In practice, for the
learner, it rarely is. The learner is focused on following your directions and getting a result; their time for wanting
to know more about the why of what they're doing will come later. By all means include links to further explanatory
material, if you feel it's required, but try to resist the temptation to interrupt the flow of a tutorial by digressing
into explanation.
Your job is to guide the learner to a successful conclusion. There may be many interesting diversions along the way
(different options for the command you're using, different ways to use the API, different approaches to the task you're
describing) - ignore them. Your guidance needs to remain focused on what's required to reach the conclusion, and
everything else can be left for another time.
Doing this helps keep your tutorial shorter and crisper, and saves both you and the reader from having to do extra
cognitive work.