In your own opinion, what makes a tutorial beginner friendly?

#discuss #beginners #writing #programming

I asked this question on Twitter (sorry, X) and got some amazing responses so far. Thought it'd be appropriate to ask here as well. 🙂

Top comments (6)

Schemetastic (Rodrigo) • Jul 28 '23

For me, it would be that it doesn't assume that I just know stuff, so if the tutorial won't cover some topics, it is nice if they tell you ahead, “you need to know about this stuff, so you can follow through” that allows me to research about what I need to know, and is nice if they explain you some terms that are specific to that area or topic.

Tracy Gilmore • Jul 28 '23

IMO, Starting with first principles and building up gradually. I also think keeping it fun is important for all learning.
Tutorials are, understandable, typically written by those well versed in the topic but are intended to be consumed but those new to the subject. It is important, as the author of such material, to get feedback from 'test' consumers and continually refine the material.

Check out The Feynman Learning Technique.

Quinten Konyn • Jul 30 '23

A beginner-friendly tutorial needs to justify its decisions. No need to go in-depth and overwhelm or distract the learner, but enough to invite the learner to see an example of how to cope with all the conflicting advice they're given, and start developing their own opinions.

A beginner-friendly tutorial needs to explain how a beginner might have been able to access the information and develop the strategies used in the tutorial. That could be quoting official documentation for key concepts used, or the author describing their thought process in a humble and demystifying way. (Show the conceptual dead ends and how to recover.)

If it doesn't have those features, it's either a procedure for the learner to follow without fully understanding why or how to generalize it, or it's extra-fluffy documentation. Those can both be useful functions, but it's not what a tutorial needs to be. A tutorial needs to teach generalizable skills and knowledge through the medium of a concrete procedure.

I don't find many tutorials that hit the spot. They're probably very difficult to do well, and I know it's a big ask. I prefer overview-style introductory documentation, but that's usually not very beginner-friendly if you're also a beginner to reading documentation!

My first coding was taught through a mentor, a bound-book copy of game-making tutorials, and official documentation. And oh boy was the book the useless one, out of the three. It wasn't thorough like the documentation, and it also didn't teach those wishy-washy problem solving skills like the mentor.

But considering how inviting and accessible tutorials are compared to documentation and years of time with a wise mentor, I hope people are thinking about emulating some of the features.

Jean-Michel 🕵🏻‍♂️ Fayard • Jul 29 '23 • Edited

It's important to define the audience
Who should read it?
What they will get out of it?
Why this matters?
And more importantly who should NOT read it?

I have nightmares from reading the Android documentation spending hours to read very complex and frankly badly designed stuff, trying to make everything work, just to realize after all that work that it didn't make sense at all for me to use those APIs in the first place.