Comment by BiteCode_dev | Hacker News Reader

Comment by BiteCode_dev | Hacker News Reader

Lot of good advice.

I'll nitpick a bit.

You can't tell your user to "echo 'awesomecopter' | sudo tee /etc/hostname" if you may have windows users.

And even for purely linux user, "Good: Give the reader a bash snippet that evaluates conditional logic for them" is quite a scary wall of code for a beginner that as no idea why copy/paste that.

All in all, don't confuse "giving the shortest path to a working solution" and "teaching", which both can be in a tutorial, but they have different goals and you should choose accordingly.

I think the "Teach one thing" is probably the best advice in the article, and too often ignored. I remember as a kid reading Swinnen's book to learn Python and having to understand OOP with his example using ions was a terrible experience.

And if you think "well you should have known that, they teach it in school", you are missing the point.

That being said, writing an excellent tutorial takes a lot of work. Way more than a good-enough one. Choose wisely.

I really wish more tutorial makers would do the "teach one thing". Like I dabble in gamedev, and most people who create content for it generate 45 minute to many hour long tutorials that are end to end, instead of teaching "this is how you deal with navigation" "this is how you handle movement" etc. Means people who want to learn stuff are stuck interacting with a massive block of stuff which makes extricating out the part they need and planting it in their own project wildly harder.

Yes, and then link this things to pre-requisite, and show how several of those one-things come together in a separate piece.

But again, it's a LOT of work to do that.

E.G:

To write "https://www.bitecode.dev/p/back-to-basics-with-pip-and-venv", I need to be able to rely on "https://www.bitecode.dev/p/installing-python-the-bare-minimu..." which in turn needs to rely on "https://www.bitecode.dev/p/ultra-beginners-first-steps-for-t...".

That's almost 9000 words, or 10% of the average novel size just to give beginners a good chance of success on one single topic.

Between doc, tutorials, FOSS and forums, the entire software industry is just standing on a gigantic pile of billions of hours of free labor.

I won't disagree with that. I will say pip and venv ending up being a massive chain is entirely unsurprising because Python environment management is a mess to begin with. But then there are a lot of gnarly topics that can be hard to find useful information on.

One thing that doesn't help all this is more and more tutorials going on Youtube (I admit I've made a couple, which were topic focused) is that so many people just want an entire soup to nuts answer instead of the tools to piece together their own solution from the parts, which makes gaining traction and getting that information to people a lot harder.

But without a general change in how people look at learning I dunno what fixes that problem.

Reply on news.ycombinator.com