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

People make tutorials for economic reasons, those reasons are not always 100% aligned with the need to help you learn.

Making the tutorial increases their profile, leading to more profitable opportunities elsewhere (because making the tutorial is not as financially remunerative as actually being employed/consulting somewhere).

Furthermore if you make a tutorial as an advertisement for your skills you want to make it as quickly as possible and show off skills that an employer will appreciate. Probably the quickest way to do something, or to decrease the cost of doing it is to work on something you want to make anyway or to adapt something you already made for a client/project. OF course the easiest way is for people to just go ahead and take the official documentation examples and tweak them a bit and now we have a new tutorial showing you how it is done and we have also managed to improve our profile! Everybody wins, only you don't win as much as the tutorial writer.

Because you want to show off skills to the employer you might also have to consider what the skills you think make you bankable - especially if you have a plan as to where you're going. So even though your GraphQl tutorial might not need much on the frontend you may want to throw React/Redux in there because

1. you're good at React/Redux so gotta show that off 2. more code looks more impressive to a lot of people.

Finally, When you make a tutorial on GraphQl you will need to have some sort of backend, frontend etc. so you have to choose something, probably you decide to put those together based on what your skills are, based on what you have that you've worked on that can be adapted to tutorial purposes, and a number of other factors.

At any rate there is not much economic incentive for most people who make tutorials to make the best tutorial for educational purposes that they can make, unless it is their plan to be educators in the future.

Well there are multiple things that "simple" could mean. If I'm looking to learn about construction, why not start with sticks? I already know exactly how sticks work. I can find them on trees, lash them together with bits of bark or just fit them together with friction, and there you go. Sticks are simple!

But what if I want actual walls? Insulation? Fireproofing? Waterproofing? Wolf-proofing? Oh my god, no, don't start with that "it's simple with concrete" stuff again. I get lost every time you get into nominal mix ratios and slump. Concrete's too complicated. I know sticks. Can't you just show me a simple way to do it with sticks?

The two kinds of simple here are conceptual simplicity and practical simplicity. The former is easy to understand; the latter is easy to do something with. Conceptually, a coffee machine is way out of my league: fluid dynamics, steam pumps, PID control... that's some serious stuff. But to use it I press some buttons and coffee comes out.

In software, it's possible to make things that are both conceptually and practically simple, but it takes very careful and deliberate design work. The function, say, is a building block that can take you all the way from int main(void) to AWS Lambda. But modules vs classes vs namespaces vs packages vs bundles vs environments? Forget Promises, we still haven't got a simple design for how to group data and code together.

On top of that, the incentives rarely line up. By the time most people get to a position where they can design their own materials, they've forgotten that sticks ever seemed complex. Most libraries are written by professional developers for other professional developers. Professional developers are paid to write code that does stuff, so practical simplicity tends to dominate.

Even amateur audiences for tutorials and the like often prefer practical to conceptual simplicity. They want to copy-paste some code, press run and change a few lines over and over again until it works. Sure, that makes them bad software engineers in the same sense that I'm a bad coffee engineer, but they don't want engineering, they just want to make something that works. "Learning how to make things work is engineering!" you explain. "But I just want this one thing to work", they reply, forgetting this is the fifteenth thing that didn't work.

So there are a bunch of reasons why tutorials tend to use lots of "rest of the owl"-style libraries. I agree that this isn't a great way to learn the fundamentals, but I'd argue that most people don't really want that. Maybe you don't either – have you tried doing it without all the libraries? Perhaps "what you came here to learn" will turn out to involve a lot of other things that are conceptually simple but delay your progress towards achieving a practical result.

The old saying is designed to make those who cant teach feel good and superior on expense of those who actually spend time to do something useful.

Teaching is a skill. Criticism can help people to learn how to do it better, devaluing everyone who even tries leads to culture where people won't put effort into it even if they could be good. All that because someone needed to feel superior for doing nothing.

I once came across a variant:

"Those who can, do. Those who can't, teach. Those who can't teach, CONSULT."

Good question. I struggled when I wanted to try some API sample code and I had to start by configuring Yeoman, brew, and whatever other infrastructure just to get to the point of being able to run a "simple" sample.

I have also been to 4hr workshops where 3 hours was taken to help students get setup with whatever environment we were there to learn. It would have been trivial to setup remote VMs.

An even more interesting question is how to keep tutorials executable as the underlying technologies evolve. This is a big problem with older books where code doesn't even compile. Microsoft Press is especially notorious for this.

I agree that combining technologies does not make sense. There is one very good approach I've seen used by the Meteor book team. I will use the same approach for writing tutorials for my technology.

The entire book is valid Meteor code. As it evolved and broke compatibility between 0.8 and 0.9, the book became outdated. However, the team continued to evolve the code.

Their approach was centered on checking out the next branch instead of typing it manually as you read. As you start reading next code listing, you can type "git checkout chapter4-1", for example. So, as the code would evolve and no longer function with latest version of the framework, they would update the branch tag and it would magically work again.

Although the code hasn't been updated since 2017, you may find it very interesting. If you run it with that era's Meteor, it will still work despite the code being largely irrelevant today https://github.com/DiscoverMeteor/Microscope and the http://discovermeteor.com site explains its rationale to end their involvement in the project.

One of my pet projects is to fully explain how to implement oAuth. If you can fully understand how to implement Salesforce login, others are cakewalk because they mostly omit steps that Salesforce chose to implement. I have a few ideas how to do it, but it may be a challenging task. Still, it's the most sticking point I see for newer developers who want to deploy usable code. It starts with calculating base64 header values and then they throw digital signatures and expiring tokens at you. In other words, have fun interpreting this tutorial. ;) https://developer.salesforce.com/docs/atlas.en-us.api_rest.m... It tells you what it expects but not why it expects it.

Twilio explains it fairly well, but expects you to implement itself using its SDK.

My intent is to build a comprehensive site that supports multiple languages to implement oAuth starting with plain JavaScript and a handful of select platforms and then adding support for other languages to get to the point where official documentation finally makes sense.