What makes an excellent tutorial?

• How do you know if this tutorial is actually going to help you learn something?
• Is this going to be too easy or too hard?
• Am I going to learn how to draw an owl like this?

As part of my newsletter each week, I share tutorials and resources that I’ve found most helpful in escaping tutorial hell. I’m trying to place these in a wider context and encourage readers to take the next steps in their learning journeys. I work through a lot of tutorials and write some of my own. Some exploring concepts I knew previously, others stretching me in new directions.

Here is my current understanding on what makes an excellent tutorial. Be warned, it is a high bar and I find it hard to place a lot of my creations in the excellent bucket.

1. Can be read at multiple levels

For me, a tutorial that is useful for a beginner while also giving insight to the more advanced user is a winner. If I can read it to find the missing step in my thinking and learn a new process then I am very excited. I want the article to be beginner friendly without being tedious. I also want it not to assume too much prior knowledge. I get that this is a hard line to walk though.

A way that my favourite tutorials manage to do this is by use of metaphors and analogies. Where these are used well they help close some conceptual gaps and deepen learning all round. If there are images as well as a wall of text then that quickly moves you up in my estimation too.

2. Quick wins

When I scan through the tutorial, I want a quick win. I might have just come for a key point or insight - the missing step that I’ve left out. In which case, I’d like to be able to scan the article quickly and find the right piece.

I want this tutorial to help me achieve my goals and to reassure me that I’m moving in the right directions. Check-in points can help here - telling me what I should be seeing on my console or screen if I’ve done this right. Sign-post me to success!

3. Zoom in and Zoom out

I like a good walk-through from start to finish. I’ve learnt lots from some of these longer form and detailed approaches. But, I’ve also got stuck because technologies have moved on slightly and the exact commands don’t quite work.

Where the author has zoomed out and helped me to understand why I’m doing something and what I’m trying to achieve, this isn’t a huge problem. I understand what I was trying to achieve and am equipped to debug the issue. I want to regularly zoom in to the nitty-gritty of what I’m trying to achieve and zoom out to the overall map of where I’m going and why.

Give me lots of examples and tell me how this fits into the wider development journey. How does this relate to something I’ve seen before? Why am I using getStaticProps here where I used getServerSideProps over there? Also, how many arguments does this function take? Give me a mix of the macro and the micro.

4. Onward journey

Point me forwards on my journey. Encourage me to put this learning into practice and give me some ideas of where I could go with this new learning. Call out to other tutorials or web sites that might have used these skills. Could I now try to build something from that website you like? Or with these skills, could I now replicate a cool feature from that blogger’s site?

Also, if I’m watching a video, could you point me towards some written resources? Or a podcast episode where the author of this library had some interesting insights?

We all learn differently and I like a mix of resources to help me on my learning journey. Help me on my journey.

5. Focus on helping me become awesome

Thanks for making this awesome content - I can see it took time and effort to pull it all together. It was an act of generosity on your part but I’m going to appreciate it so much more if the focus is on me. How can I be more badass now I’ve read this and worked through your creation?

Try hard not to make this about how clever you are but how capable I can be with your help. Help scaffold my learning and allow me to know I’m making progress. Encourage me to blog or tweet or build in response to what you’ve done.

---

I think I have a pretty high bar to what I think is an excellent tutorial. I’m always searching for more and try to share the best of what I find in my newsletter each week.