there are three kinds of programming tutorials:

• “look man we both know you don’t wanna learn this shit so just install 30 GB of random frameworks and here’s the code to copy-paste if you wanna make a basic game and feel like you accomplished something. I’m not gonna explain how any of this works because nobody cares as long as your little guy jumps when you press spacebar”
• “an endofunctor is a type of monoid which is a subcategory of monad that is variadic over the set of all impure lambdas - therefore all possible expressions in this language can be modeled after- wait where are you going?”
• “this is called a variable! a variable is a little friend that can hold onto something called a value! variables love grabbing values and they can even carry them into functions! say hi, variable!”

@kasdeya honestly, i kind of like that third kind of tutorial, but they never seem to go on long enough to cover more advanced concepts in that same voice

@smolcasm I actually really do too lol. the cutesy comparisons hold my interest and help me understand things much better. I once found a FORTH tutorial that anthropomorphized all of the different FORTH keywords as different characters and machines and it was super cute

@kasdeya we have seen tutorials that clearly lay out "this will teach X, but not Y, and you are expected to already know Z. If you don't know Z, here are some resources to go start with. If you're finished learning X and need Y, here's where I'd go next"

. . . unfortunately we've seen all of like 2 that considered this, there really need to be more

@tempest I would love to see this more often tbh. I think it’s really important to consider what kind of audience you’re writing a tutorial for, and explain that at the start. it helps the reader a lot, but I think it probably also helps the writer too - so they explicitly know what audience they’re writing for

@kasdeya Brodie, "Starting FORTH", 1st ed, 1981 is a tour de force of the third category.

There's now a PDF:

https://www.forth.com/wp-content/uploads/2018/01/Starting-FORTH.pdf

@kasdeya A lot of tutorials I've seen struggle with just keeping a consistent level for a target audience
Like explaining how to set up an IDE and then not explaining basic programming concepts

@kasdeya oh wow, this just clarified a bunch of the "I use AI for programming" mentality for me.

@kasdeya Thanks, I hate all of them. 😂

@kasdeya

#3 is the entire "head first" series, and my #ADHD brain is totally here for that.

SQUIRREL!!!

@kasdeya
Hi variable! ❤️

@kasdeya I wonder where the NeHe tutorials fall in, as in here's a complete program in snippets and I'll explain each snippet, better pay attention..

@kasdeya

I was learning JavaScript and reference was made to an iterator, without any explanation as to what that meant. So I looked it up. The definitions I found were all some variety of "an iterator is something you iterate over." OK thanks.

@kasdeya This is so accurate.

@kasdeya Which is why most people are afraid of programming and/or see programmers as condescending assholes.

@kasdeya When I was first learning Python many years ago, I came across all 3 of these. The best ones always told you to go read the documentation, but as a newbie just starting out, docs are freaky. They're written for coders who already know how to code in other languages.

A lot of the docs include a tutorial now too, which is wonderful.

@smolcasm @kasdeya why the lucky stiff’s Poignant Guide to Ruby came close IMO.

@kasdeya Especially learning a functional language exposes you to the second one. "I want to learn Haskell!" "OK, start with understanding this academic PhD paper…"

@kasdeya Isn't there a fourth one where the person is figuring things out and building the thing as they go? It can be very good or bad depending, amongst other things, on how honest they are about it. It also often abruptly ends after a few chapters/episodes without any explanation.

@kasdeya

Holy shit! So spot on!

@kasdeya @smolcasm @agatha Honestly, Learn You a Haskell is not far off https://nostarch.com/lyah.htm https://learnyouahaskell.github.io/

@kasdeya if you want me to actually try learning a programming language imma need a tutorial that frames it in terms of casting magic spells cause as far as I'm concerned these are magic incantations

@kasdeya in these days there’s a forth one:
„Use ClaudeOG, Opus and SonettGPT agents to vibecode the first 10 million LoC, the resulting abomination will then refactor and maintain itself, obtaining generic singularity within the next three weeks“

@kasdeya @smolcasm
I learned to program in BASIC from a book that depicted the 8-bit computer as a cartoon character
https://archive.org/details/getting-started-with-color-basic-1984-edition

This inspired Taylor and Amy to create a physical mascot
https://youtu.be/lsOtBIVRnyE

@ciourte @kasdeya Oh dear, now I feel seen...

@mayintoronto @kasdeya
Early Python documentation was able to adopt the gradual baby steps tutorial approach because it didn't yet have very many advanced programming features. No need to teach newbies about lambdas, list comprehensions and generators!

@kasdeya There are exceptions, of course. The #Rust book and tutorials are fabulous.

Ultimately though tutorials are intentionally stupid; if you can't read the manual, the best we can do for you is patronize you into thinking you can be a programmer, without reading the manual.

@kasdeya

Say hello my little variable!!!

@danlyke @kasdeya
People new to programming treat any confusing computer science jargon (WTF is a monad?) in the tutorial like a deep rabbit hole or distracting side quest that risks derailing them from what they wanted to accomplish—"I just wanna make a cool 3D interactive animation for my twitch stream/social media" so turn to AI then hit the discord for help when their slop doesn't run. The discord regulars don't take kindly to this, refuse to help, and so get accused of "gatekeeping"

@kasdeya true! But how about a fourth category that would be :
"Indian developer goes straight to the fucking point with very down-to-earth explanations"

@bornach @kasdeya @smolcasm oh that book got me through 9th grade

@kasdeya i've been a proffessional programmer for fifty years and i'll take door three, please. hello, little variable! nice to meet you!

@khleedril @kasdeya
And it is at that point they go ask ChatGPT to generate the code. Who has time to read a tutorial and consult manuals when there is a social media channel demanding regular content uploads?

@mdreid @smolcasm @kasdeya we need weird as well as cute. he was the picasso of programming tutorials. we were so, well, lucky.

@lanodan @kasdeya i start with the cute tutorial, and then at some point i have the manual open too and read them both at the same time…

@raymierussell @kasdeya
That brings back memories.

I feel like I'm 9 years old again reading this

@kasdeya recently found https://learnxinyminutes.com/lua/ which doesn't fit really, and is pretty neat :-)

@RoseThorndyke
Yeah, I was trying to classify CodeCrafters in this, but they're more like, "Let's build Redis! First, you should listen on a port and echo what's sent to you."

That may be a subtype of the endofunctor example?
@kasdeya

@ciourte
Isn't that less tutorial and more self-exploration?
@kasdeya

@kasdeya Every time I've tried to learn, it's ended up being type 2. My brain does not enjoy type 2.

@AbsentAbigail @kasdeya I think that happens because they understand that part well enough to teach it, but they're fuzzy on the rest so they gloss over the bits they don't understand about the more advanced material.

@kasdeya
Mainly this + dating and version mapping, boldly right at the top!
@tempest

@fishidwardrobe @lanodan @kasdeya ideally the tutorial will provide relevant references to the manual

@kasdeya You nailed it.

There is one more though: "In this series of tutorials I will teach you everything you need to know to make a metroidvania." --Part 3 of 20, on hiatus for 5 years.

@6d03 @lanodan @kasdeya i love it when they do that. i end up with two dozen tabs open

@kasdeya
I suspect good tutorials
a. Pitch to the intended audience at an appropriate level
b. Pick ONE intended audience
c. Pick ONE concept/goal to use the tutorial to explain
d. Have a reference to the appropriate docs at the top
e. Put installing the product details in a separate tutorial and make it a link in the start of the main tutorial (eg make installing Nginx a separate tutorial from how to setup Nginx as a reverse proxy)
f. Make it obvious what version this applies to + a date
g. If there are different alternatives for parts of the process, then acknowledge that and perhaps describe how and why to choose and even have sub tutorials for not just your favourite. Eg there are many Web servers you could install.

Could go on, no doubt...

@dpflug @kasdeya I was more thinking of Unity tutorials that go like "first, we're going to create a game object. Then, we place it on the screen. Then, we create a script in the script folder and attach it to the game object."

Straightforward.

"Use the source, Luke."

@kasdeya

@kasdeya I learned the basics from this:

@RoseThorndyke maybe I'm unlucky, but the Indian tutorials are like #3 with creepy, distracting graphics and mentions of "love" thrown in like it's an uncomfortable requirement.

@kasdeya

@shadowfals @kasdeya Jesus fucking Christ

@kasdeya the third category reminds me of why's poignant guide to ruby which is one of the few books on a programming language that I read entirely

@kasdeya 2 made me laugh and 3 made me recognise my own teaching style (a little less cute but in principal that is it)

@kasdeya 4th: https://sourceforge.net/projects/graphics-programming-bb.mirror/
Or old-school 6502 assembly books. Toss you in the deep end, you learn what you need or drown.
#gamedev

@kasdeya I feel like I learn more by figuring things out myself rather than reading a tutorial

@kasdeya
You forgot the very common hybrid of the last two...

@bornach @glassresistor @smolcasm @kasdeya i inadvertently taught myself to read so that i could read this book, then i started kindergarten reading at a third grade level

@elexia there’s a Minecraft mod called Trickster that is literally “what if casting magic spells was a type of programming?” and it honestly fits so well lol

@kasdeya i love when im trying to go for the second one but i end up with the third for 30 minutes as they explain how to setup the environment. meanwhile the one thing i wanted to learn from the tutorial is at like 33 minutes 42 seconds in

@kasdeya hi, variable!

@kasdeya oh that sounds fun

@kasdeya Which makes you realize the gold you've struck when you find a tutorial that takes the best of all 3 and dumps the worst parts of them.

Such a small fraction it would be dishonest to not call them outliers.

@kasdeya I usually run across a fourth kind: "Get started by installing this package and running this command..." which turns out to be six weeks out of date, NOBODY uses that package any more, if you try running those commands you'll just get an obscure error. The forums are full of people reporting that error. One in ten posts get a reply saying "that doesn't work any more". One in fifty has a reply of "Use this other thing instead", without explaining how.

@kasdeya Hi Variable!! 👋

@kasdeya and they all drive me insane!! Sometimes i know the basics i just dont feel like spending another 5 hours in the documentation

@kasdeya hi variable! Nice to meet you

@kasdeya
Which category is having to strictly follow a step by step physical book to make a (very basic, no html) website in Google Sites?

I feel like probably the first

My highschool tech classes were... sad

@kasdeya I'm gonna have to go with Door #3, Monty.

@kasdeya
I want 3 slowly digging down towards 2 ;-)

@kasdeya @elexia oh hey, i remember playing with this during (if i remember correctly) the blanketcon 2025 mod fest! was a cool mod :3

@kasdeya I have seen others, but neither many nor were they all so much better than your archetypes. But yours are much funnier.