Ask HN: Why do tutorial writers combine 10 technologies when 1 or 2 would do?

The other big thing with tutorials that I've seen is trying to introduce many build tools at once. Lots of people have enough trouble even getting Node to run on Windows, so requiring Node and Babel and Webpack when you could just pull in jQuery in a script tag and have a simple index.html might not be as realistic, but it gets readers to the meat of the exercise faster in my experience. If you're trying to show me how to use Highcharts, just include an object containing the data in some inline JS in index.html, or at most have one non-minified JS file that gets included in index.html with a note in index to look there for the JS.

Docker can be another one that some engineers forget isn't trivial for most people to set up. If you're hoping for people to pull half a dozen images and get them all networked together, you might lose a lot of people right there. Focus on delivering value for the reader; show them the cool parts of the thing you're talking about, and minimize absolutely everything else that you can (unless you're also trying to e.g. show how to integrate a few disparate systems or something, but then make that a separate tutorial).

This is exactly right. When I was an absolute beginner I tried learning things from tutorials and I even made a few myself but now in know more I learn everything from the documentation and posts on stack overflow.

I'm dealing with this conundrum. I'm working on a Kubernetes course, and that's kind of pointless unless you deploy an app with containers. What app? I've settled on a smallish Rails app, though I realize many students won't be Rails developers. Additionally, I also realize many deploy targets for Kubernetes might be cloud specific (AWS, Digital Ocean, GCP, etc) Do I ignore those differences, or try to address those concerns?

I have some thoughts on this. Last year I wrote a book[1] and my primary goal in putting the book together was to write the kind of book I wanted when I was a student in the subject. I wanted to teach in a manner which was as direct as possible without burdening the reader with an obligation for prior knowledge, where each chapter is _just_ challenging enough to guide the reader into doing their own informed sub-field research and where no concept is introduced before its time or, worse, required at some great distance from its need.

That last is where I think a lot of tutorial material gets hung up. You, the author, have some end goal of knowledge in mind and know that you, the reader, will need to know this, this and that. In what order should this, this and that come? If they're all excessively complicated how do you as an author make sure that the reader comes away with sufficient grasp to move forward in the book. It's very tempting to solve this problem with a "looping" style of writing. That is, you lay down all the concepts you know the reader will need in a big hurry in rough detail -- promising that, don't worry, we'll come back to this and it'll all make sense -- and then, once this is done, start in on the material you intended to teach. But, the reader is lost, right? There's almost no chance that the rough background laid out is enough. So, you pause the main material, loop back to one of the background bits of knowledge that need to be fleshed out and go back over this before returning back to the original main material context.

Personally speaking, as a reader, this stinks. It's hard to keep in mind what I should be focused on, it's hard to keep in mind why I should struggle through the material if I'm not sure where it's all going. I find myself reading this sort of thing and thinking "Well, I'm pretty sure this is extraneous and I can drop it later, so I'll just skim it," which may or may not end up being true, ultimately to my hard either way. But, as an author, this writing style is much easier (at least as easy as any writing can get, on account of it is brutally hard[2]) and makes sense to you as you've already got a command of the material.

There's a related potential cause for this kind of writing: the author only understands the material in the context they learned it in. Your blockchain course author may not have JS and blockchain totally distinct in their own minds, and may view them as natural partners. Someone not familiar with Python but very familiar with JS might agree. This one is maybe tougher to get around, which is why I tried to be very clear in the introduction to my book that its aim is to teach fundamentals but that the teaching would be done in the specific context of a language and CPU families.

Also, there are solicitations for pieces which state you won't get paid unless technology X, Y and Z appear in the piece. That's an explanation too.

- - -

[1] https://www.amazon.com/dp/B07C5WXSXX/ref=dp-kindle-redirect?... [2] https://blog.troutwine.us/2018/06/07/hands-on-concurrency-wi...

Thanks for mentioning exceptions. I've found that Stephen Grider's courses on Udemy are outstanding. He's clearly found his calling in life. (I don't know him personally - have just taken many of his classes).