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

I've noticed this too. My best guess is that they're written the way the author learned the concepts, without taking the time to find "the simplicity after complexity". (https://en.wikipedia.org/wiki/Shuhari) Makes the writer's job a little easier, but the students' job infinitely harder.

Yes not to mention git and docker are now assumed.

Most tutorial writers are terrible at what they are trying to teach. They may have a vague grasp of a concept, but that's about as far as it goes. If they were more capable they wouldn't be writing tutorials.

There are of course exceptions to this, but it covers at least 90% of the people who create courses for sites like Udemy.

Comes back to the old saying, "Those who can, do. Those who can't, teach."

I think there are two types of tutorials which exist: one which provides a high-level overview and the other which thoroughly examines a subject using a practical example. The former is usually the territory of novices who want to demonstrate what they've learned using technologies they've recently encountered. The latter is quality content written by professionals who truly understand and are passionate about the subject they're discussing.

Both types of resources serve a function, but when a certain field has a low expert-to-novice ratio then it is understandable why it might be more difficult to find one instead of the other.

I have my own personal examples directory for each piece of tech I use. And where possible, each starts with just main() and zero libraries.

I do have examples hooking it up to other tech, because that's important to know too sometimes. But if you can't use something without a bunch of other libraries you might not actually understand it.

A huge fraction of the people who are trying to learn to use GraphQL (to use your example) are trying to learn to use it in the context of React and Express because they have a front end problem they need to solve with it. The blogs they write aren't really about understanding GraphQL in totality or on its own, they are tutorials on using GraphQL in a context with which they the authors (and a great many of the readers) are familiar, namely Node.js apps running Express and React.

The huge number of posts like you refer to is one of the things that draws developers into an ecosystem like React and Express. There is simply far more written about how to use shiny-new-thing in the context of solving a problem in a big existing ecosystem than in the context of pure discussion of some hot new but still largely unused tech, largely because there are so many more potential readers in that large existing ecosystem, and those readers want to read how to solve the problems they face in their ecosystem. Long ago Microsoft's Developer Division talked about this as the difference between three different developer personas. The fanciest persona was "Einstein" who wanted to understand everything about how the tech worked. The lowest was "Mort" who was a dentist who just wanted to learn to write a little bit of script to print a report he needed for his business. And in the middle was "Elvis" who wanted to learn enough to understand what he was doing and to do his work but was ok not understanding everything. Most front end devs are not in the "Einstein" category of how they learn technologies. They are much more motivated by the need to solve an immediate business problem, and they tend to do a lot of blogging because there are so many of them.

People often forget what it's like to learn something from scratch and lose touch with what is "basic." I'm sure everyone here had at least one professor in college who would go through some long and overly complex explanation, only to conclude with "see! it's so simple!" Learning to think like your audience is one of the more difficult parts of being a good teacher.

There's also a temptation to show off. I've seen people advertise their portfolio of tutorials they've written in interviews, or at least point to things they have written to demonstrate their expertise in [some technology]. Being pessimistic, if your goal is more to advertise your skills than to teach then it's likely going to turn out like that.

Lastly, writing tutorials/teaching in general is a skill that requires practice. Just knowing a subject really well by no means makes you a good teacher. To that end, a lot of those tutorials are just noise; the number of good tutorial writers is obviously much smaller than the total number of people out there writing tutorials. And, not every teaching style suits every person, so perhaps a tutorial you find confusing is perfect for someone else (and vice versa).

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 true but I've also find myself at the other extreme more and more where I can't understand how to put together two or more pieces of technology and every article just goes over only the basics.

For learning single technologies usually the documentation + some forum or chat to ask questions I don't know how to search because I don't know the terminology yet, is the best way to go imo.

Also sometimes technologies just depend on other technologies (e.g. webpack, npm, git), it's hard to make a beginner tutorial on something like that. I think it's wrong if a tutorial that covers more than the basic case is marketed at complete beginners, but also as the one learning, you have to learn how to learn. 70% of tutorials or more that you find will be useless, either because the one who wrote it wasn't good at writing, or they're outdated, or they're just plain wrong. This is normal. Of the ones that are useful, some you won't even understand until later sometimes.

Also what I find helps something click, is not always what helps others. For example, for learning languages I like youtube videos that quickly summarize all the syntax (because I already know how to program), but I can't stand "build x thing" tutorials usually because i'm just not invested in the project and anything that goes into too much detail bores me. But beginners would probably find a tutorial that includes installing things like git, npm, etc, priceless.

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...

Sometimes people do want to show off their knowledge and in the process loose touch with the needs of the student. That's why I always try to write my VUE Example tutorials in the simplest english language possible, even if it doesn't look sophisticated. https://codeorc.com

personally, I feel I learn best when learning from examples and changing them to experiment with them and find out how they work.

Most tutorial writers are not aware of how to create educational materials. They don't think deeply about the learning objectives (what the reader should be able to do or understand at the end), don't understand how to provide concise working examples, how to "scaffold" learning, and so on. It's often just a dump of the things they learned and maybe how they learned it, but that doesn't mean it'll work for anyone else.

Creating teaching materials (tutorials, documentation, etc.) is hard, and few tutorial writers are getting feedback from actual students/readers. If you're never watched how novices work (and struggle!) with the materials that you've created, you don't really know what's missing or confusing or overwhelming. Even though I've been creating training courses for a long time, I still never know whether I'm making too many assumptions about what the student knows -- this is the "curse of expertise" -- and where they'll get stuck or lost.

(btw, I talk about some of the theory of learning with examples in my "Human Learning" presentation that you can find on YouTube: https://www.youtube.com/playlist?list=PLBHctPrH7Z2-BcpRWJ0uF...)

Depends on the source. Many tutorials on Hackernoon or Medium or even personal sites are written by beginners trying to grow some web presence (if they are trying to make a career change) or just trying to edify their knowledge. It's great to learn something well by teaching another.

You end up in a blind leading the blind situation however and I find the most high quality tutorials end up being (usually) in the official documentation.

OTOH, lots of experienced devs forget the details that really get in the way! For example, I just learned I need to use an undocumented flag "disableOptimisticBPs" to enable breakpoints using Jest and Typescript with VSCode. I figured this out digging through Github issues. If I was to write a tutorial next week, there is a really high probability I'd forget this obscure step is what made my life easy.

Most tutorials are posted by devs who are sharing what they learned. Some of them try perhaps too hard to show how to do things. By 'too hard' I'm saying that they want to show you best practices in many areas rather than just focusing on the part that's new.

I just ran into this right now. Wanted to see how to do something in CSS and they had it all nicely split up with combining classes as if I was working in a shared code base. I really just want to see HTML with inline styles so I can see where to put what and not have to chase down referenced sections and mentally combine them as I go. I know how to use CSS classes vs styles but that's not what's being demonstrated here.

It can go the other way too though. Sometimes with a certain framework they only have an example in either MySQL or PostgreSQL and it's really hard to find the alternate example. Sometimes it's simple, but other times the names/versions and way to load the drivers are different. One back-end framework's most popular tutorial uses a dictionary in memory as it's model. I think using a DB is a fairly standard requirement. I didn't just want to use it for routing. To be fair, the back-end is pick-and-play, but a good tutorial should just pick one of the typical ones and go with that.

Most of the blogs I've read only show a single path through the minefield - the one that worked for them in their environment. If you have a different starting point, or a slightly different requirement along the way, they are often useless.

That's not teaching, it's boasting.

Sadly, the vast majority of tutorials are like that because their major lead generator is SEO. If you can cram 10 technologies into a tutorial, you'll end up in 10x search results.

Because they are not good teachers.

I’d taught a programming class using Pascal one semester while in grad school so I felt well prepared to teach a workshop on the language to software developers from across my company the following year. I was wrong.

The students had differing levels of experience and different backgrounds, some COBOL programmers, some Fortran, some assembly language programmers. The company wanted to have the class taught over and over again to different groups, and I ended up teaching hundreds of programmers. What I realized was that it’s hard to anticipate everyone’s sticking points, and even when you think you know a subject, an unexpected question can be hard to answer clearly enough without boring some of the class.

Even simple ideas like scope rules for Pascal required several iteration before I had good examples to explain and motivate the rules. The workshops were so much better after my tenth time through the material. It’s not surprising to me that good tutorials take a lot of work and iteration to develop.

I'm surprised at how negative a lot of people are around tutorial writers. In my (biased) experience, tutorial writers are

a) relatively good at what they do and what they're teaching, even if they're beginners and

b) definitely not driven by "showing off" or "building their CV" motivations.

Tech is hard. There is a lot of it out there. It's always changing. There are a lot of variables in terms of your set up and your needs. Maybe not every tutorial is going to solve your exact problem or remove all of your headaches, but imagine trying to work all of this stuff out without the amazing resource of records of other people trying stuff and taking time to explain.

Apparently back in the day, this was done over email and IRC. You would wait days to get an explanation from someone and some code to try out, and spend days hacking at stuff trying to figure it out for yourself.

Now you can find a tutorial that's specific to your needs and if you don't like it, you can read through 10-100 others.

Tech is hard, and tutorials aren't going to fix that. You'll still have to battle through your issues, alternating between emotions of "this is impossible. I'm not competent enough" and "OMG it works this is amazing". That's most of programming. If you don't like that experience, it's probably best to pick a slower moving field.

That's the "tech is hard" bit. Now writing. Writing is also hard. And because since school most people are put either into a "Arts" bucket or a "Science" bucket, very few people take time to figure out how sentence construction works and how to piece if statements together. It's quite admirable that people who have actively hated and avoided writing for most of their lives still see a gap and try to fill it by writing explanatory materials, usually for free.

And then there's education which is hard even if you're good at writing and good at technology. The curse of knowledge is a big hurdle. Finding the correct balance between maintaining a focus on one thing and giving enough context to that thing that you're explaining is hard.

So yes, I highly encourage everyone to get better at writing. Better at education. Better at technology. But to be good at all three is rare, and most of these people find they fit pretty well at universities as lecturers, where only a very limited number of students have access to them.

If you're keen to help fix the problem that you point out, add your voice. Spend some time writing a high quality tutorial after you find the solution to a problem that you're having. Find time to edit the tutorial for good flow, bugs, and everything else that makes a tutorial frustrating to follow.

I maintain a short list of technical writing and publishing resources [0], which I'd love to see more contributions to. I also write tutorials for CodeMentor [1], and a few other places[3]. Technical content is hugely valuable, so if you're interested in contributing, it's usually easy to find community editors at large sites who will give you free guidance and editing, and often even pay you for your content while letting you keep it under an open source license.

If you want help or advice on how to write, this is an open invitation to contact me through Twitter or Email and I'll happily look over your drafts, discuss outlines, or generally help you become a better writer.

[0] https://github.com/sixhobbits/technical-writing

[1] https://www.codementor.io/garethdwyer/posts

[2] https://dwyer.co.za/writing.html

For basic tutorial, I recommend to just read from books or official web site. Integrating multiple technologies is another problem I face mostly, so those online tutorials help a lot.

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.

Its for SEO

They are signaling to people that will never use their tutorial about their prowess

Many people fall for the “mega-talent” allure

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.

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.