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

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

143 pointsakudha78 comments

Suppose I want to learn graphQL - most of the tutorials are a combination of express, react and 20 other things, when most of these aren't going to help me learn what I originally came to learn. I saw a course on blockchain which explicitly stated it is for beginners ("no coding experience necessary") and they picked JS along with 5 other JS frameworks to build a simple toy blockchain when Python would have been a much simpler choice (most of the students were struggling to understand JS Promises and unable to complete the exercises).

Isn't this crazy? I can understand paid courses doing this - maybe they think they're providing more value for the money by tacking as many tech as possible, but free resources? Even they do the same!

View on HN

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

Teaching is a skill and like any other skill, it needs practice. I have immense respect for teachers who have dedicated their lives to perfecting their craft.

I had this realization after we found a solid preschool for my kid, after having been at one that was just ok. Same with piano lessons. There was this moment where I just went, “oh, that’s how you do it.”

Even as someone with the flexibility and time to be a part of my kids’ educational experience, I now have an enormous appreciation for what a good teacher is capable of. They’re almost always several steps ahead of me, introducing concepts I hadn’t thought to introduce, in ways I hadn’t thought of doing it.

But also like learning any skill correctly, one needs knowledge. Feedback during the practice helps a lot to make sure what's being practiced is correct.

Teaching, instructional design, curriculum development, etc., these are knowledge-based skills just like programming, but without the automatic corrective feedback that a compiler or automated test gives you.

I think, many teachers either lack important knowledge or they simply don't know that what they know is important to understand the bigger picture. Others include unnecessary information.

I teach different courses (database architectures, programming and cloud computing) at universities and the most challenging part is to figure out what questions students might have and how they think differently about contents. I update my course materials and exams every semester based on their feedbacks and based on solutions provided.

And you are right, that is not something that one just can do, it's a skill to be learned and needs constant practice.

It is called "the experts blind spot"

Yes, also known as the "Curse of Expertise" or the "Curse of Knowledge", is a big part of it, but being aware of it is just the start. Understanding how to break down the skill into the pieces that the learner can absorb is one of the hardest things to 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.

Does it really work this way? I suspect that tutorial writer who expect basic tutorial to be treated as major showcase is deluding himself. No employer is impressed by basic tutorial on something nor by express being mentioned in it in basic setup.

But the whole complaint of the Ask is the tutorials aren't basic, and nobody is writing the basic tutorials because it doesn't benefit them. It benefits them to throw a bunch of stuff in there to show they follow best practices (like putting a complete test suite into your tutorial). Throwing a bunch of stuff in the mix and showing basic competence also causes people to think they have more than basic competence, because who really performs at their highest for a tutorial?

It's not something that you expect an employer to be impressed by in itself, it is part of the whole package - imagine Cuba Gooding Jr. saying 'The Kwan' - a resume of interesting things or maybe just reasonable things, a github profile that has something reasonable in it, writing on subjects that show the keywords we look for that helps them stand out in the crowd. I'm pretty sure I remember reading to write on technology as a recommendation to young developers who want to build 'Great Careers!!! SQUEE!!' (the squee is my cynical, sarcastic side reacting against the pumped up excitement of building great careers)

But writing a tutorial that is a little bit more than basic also does other things that employers, HR, and recruiters might take as being important.

1. it shows communication skills, someone who can communicate in writing will hopefully be able to communicate verbally with our team, customers, whoever.

2. If they can write a tutorial maybe they won't be like all these other developers we hire that don't document anything and then the next batch of developers come in and say damn nothing has been documented.

3. They at least feel comfortable enough with this technology to write something down and publish and I looked at the comments and nobody complained they were a hack or sucked, and some people said thanks so I think they should go into our pile of maybes.

I think I know which article you mean, but I really don't think it works that way - on either end. Companies just don't care about your writing. And had they cared about documentation, they would reward writing documentation and people would be more likely to write that. I mentioned express in tutorial about graphql does not seem to me proof of anything much less about such person being comfortable with express. It usually shows that you know that it exists, you can do basic coding and that is pretty much it.

People who write tutorials gain very little from it. The structure is more often determined by mimicking other tutorials, writing for himself (e.g. people exactly like me because that is easiest) and writing in a way that is easy and quick to write. Or even more directly, writing literally for yourself so that next time you are wiring the same thing, step by step is available. That is not laziness, before somebody throws it, they are already doing more then those who don't write at all.

It is really often written while that person is learning new technology where writing helps you to learn and allows you to keep log. Writing in depth is harder and takes way more time then people who never tried assume.

It might not work that way, I'm just going on things I was told back when I was writing (which was before the landscape changed and you could actually sell technical articles and get paid money for them [so different circumstances but similar incentives I believe], I don't know where you get that anymore [maybe some places give you money based on traction after publication]), my own reasons for writing, and the aforementioned article.

In the case of my own writing it was because I was a very XML guy and I wanted to give some impression of "he's not just an XML guy" if the wind ever changed and I needed to change with it. They have, as far as I know, been useful two or three times in the context of employment, but not exceptionally useful, and one of those times was impressing the social media engaged chief at the worst job I ever had in my life who thought doing the articles and so forth was a marker of senior engineer behavior.

And I'm not saying it will have the actual effect described every time or even frequently, but I do think that a significant number of people believe or hope it will.

Great response!

I always suspected that the motivation for writing tutorials was to showcase the skillset and, of course, the more ... the better. Hence the cramming in of as many technologies as possible into a single solution.

I don't think I'm the exception but I don't write tutorials for money or fame. My name isn't even on them directly. The only way to see I made them is to click the GitHub link which I doubt one out of 20 people click.

I think it's just fun to teach. The only other motivation I can think of is it's also frustrating to see people follow bad tutorials full of bad practices. The only way to combat that is to make my own.

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.

I agree with everything you've said here. My mentioning GraphQL in the context of having a large impact on how/if back-end dev is done. It's somewhat like serverless where front-end devs can do it all themselves. As you mention its effectiveness comes from the number of front-end devs building applications.

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

It's interesting to watch people make inferences about the capacity of individuals to develop software based on the utterances of a 19th century Irish playwright.

My theory is that exposition is hard. Most people are shit at teaching.

These HN comments are pretty disheartening. What a dreary bunch.

To summarize them, people write free tutorials because they cannot do (they're bad developers), because they reap some sort of financial gain, or because they actually want to ruin an HNer's day who demanded amazing, free content.

I encourage all of you to try and write a tutorial. You'll see that it's simply hard. You have to decide on what level of skill to aim at, you need to think what this hypothetical person already knows vs doesn't know, you have to keep your tutorial aimed at this balance, you have to resist the temptation to yak-shave, and you have to resist the temptation to adulterate your tutorial with production concerns.

It's not clear-cut at all. Do you add this package because it's how you do it in production? Or do you show how to do it without it? And if you go for the latter, you probably want to at least point out that the package exists. And while you're there, why not include a quick example of how that package can sponge up some of the tutorial code? Maybe that would be more encouraging/illuminating? Are you going to help more people with this example than you're going to confuse? Is someone on HN going to call you meandering and incompetent because you chose to?

It's like trying on an item of clothing and concluding that the manufacturer is rubbish at making clothes because they don't fit you. A such uncharitably odd conclusion to come to.

>90% of all people doing something are not good at it. Why should teaching be any different than any other human endeavour.

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 think the saying you are referring to is:

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

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

Likewise Maximilian Schwarzmüller on Udemy: teaching Vue, Typescript, React, Angular, etc.

You don't realize who bad most tutorials/courses are until you encounter one that is as logical, well-explained, and progressive as Maximilian's are.

I was recommended Stephen from a colleague and now I've also enjoyed Stephen Grider's courses. I also really like them and his style! So far I've only done Vue JS essentials and Complete React Native. If I could be selfish for a moment I wish he would do at least one more Vue course with some more advanced concepts and tackling managing a large project with Vue.

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.

> Most tutorial writers are terrible

Not just writers, most tutorials are objectively terrible.

Trying to find a reasonable example on how to get something moderately complex off the ground is a humbling reminder of the Dunning-Kruger effect. The probability of an internet resource being highly ranked and visible has a near-linear correlation with the resource's unsuitability.

In fact, when it comes to technology, it appears to me that the most prominent authors are barely novices themselves. To make things worse, the instructions and "guidelines" they come up with are invariably as competent as encouraging to use SSL_NO_VERIFY flag because passing CA path is too difficult.

My mechanism for coping on the internet is simple: whenever I see a tutorial on anything non-trivial, I just assume it's been written on Sunday afternoon, after the author discovered the software on Friday night. These tutorials should be considered the modern-day equivalent of their author smiling from ear to ear and shouting "look ma, no hands!".

Which traditionally has been the augur of "look ma, no teef!"

Well you get what you pay for.

> encouraging to use SSL_NO_VERIFY flag because passing CA path is too difficult.

And if they did spend extra time on that people would complain they are trying to teach two technologies at once.

Also that’s something everyone unless it is part of their day job has to look up a tutorial on how to do it.

Just a passing “this is for ease of use, don’t do it in production and consult a manual” would suffice.

In the back of my mind I always hope that a new technology I'm using will fail in a spectacular, obvious fashion as soon as I use it wrongly, because that means that a great number of resources will soon appear to cover all the gotchas.

It's the ones where spotting and debugging the source of the problem depends on fine-grained conceptual understanding, that leads to documentation that gives you a metaphorical blank stare and shrug.

And those who can neither do, nor teach, rebel.

I once came across a variant:

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

And those who can, were taught.

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.

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.

This matters.

It may well be the tutorials are perfectly fine, depending on who you are.

I find that they way we organize and search for information through algorithms offered by the likes of Google and YouTube offer you this "10 sizes fit most" type philosophy where you get several results and they are deemed "the best" and you can self-select into using which tutorial is the most suitable for you. Though it may be the case that none of them are suitable for you, despite them being suitable for others.

Can you even conclude they are bad? I don't know.

I think there is a deeper lesson. It's not likely a situation arises that satisfies everyone and it's not likely you can tell when it is the situation that is bad or whether you are just not suited to it.

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

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.

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

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

Wouldn't the answer be to just provide a docker-compose.yml, and tell the user to run the appropriate startup and shutdown commands? I wonder how many have installed stuff via `brew install` and later have all these services running that they never needed but for that one tutorial.

> Wouldn't the answer be to just provide a docker-compose.yml ...

Sounds ok in theory, but things like having to slightly customise one of the images just to work in your environment (eg add a https ca chain), especially when the base image they used is unfamiliar... can be a real pita sometimes.

Sometimes it's straight forward, sure... but why add the extra complication? :)

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.

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.

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.

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

The answer my friend... is blowing in the Wind.

I can do way more(orders of magnitude more) with less resources in Lisp and C-python and very simple JS than most of those frameworks do. But it took me years of learning to be able to do that.

The alternative is just having frameworks that have everything that most people will need prefabricated. This way beginners could use them easily if they do not get out of the paved way.

When they want to get out of the paved way and do something else... well, there is another framework for that.

The fact is that from an economic point of view, if you market your courses for the general Public(in the millions) , those people(most of them, 90% or so) do not want to invest what it takes to become an expert in this particular area(or any other by the way).

Most of them just want a pill that fixes their problems as fast as possible, an instant gratification at the minimum possible cost(free). They want a job, they have heard this is the future, they want money to pay the rent.

Those people in the end spend way more time always following the new fashion, the new trend, the new bubble, instead of learning the fundamentals that never change.

If you market your courses for the General population at free prices, IMHO there is no other way. General population is not going to change, they consume porn(fast sex),fast food and fast education.

For me, it will be crazy if paid courses were like this. I spend my money on paid courses(some of them expensive) and certainly they are not like this.

Having done this recently, I think I can explain.

For most techs the documentation or website for that tech explains the simplest use case. For graphql, from your example, the guide for graphql is really clean and thorough and doesn’t depend on you knowing anything else.

But it’s also completely useless when it comes to implemention for the average user, who probably doesn’t want to design a graphql server and frontend from scratch. Implementation is where the work is, and it can be very difficult to implement a working example in a real application (which often have more complicated things going on).

With graphql, you won’t be able to experiment with it without both a backend and a frontend. By necessity that means you need a server (express or tails or whatever) and you’re probably using React or something similar in the frontend.

JS in particular is also kind of a mess in terms of ecosystem. That’s a whole other can of worms.

I’ll take a charitable approach to this and say that the authors probably realize that people want to make something visual with this skill. The author only knows a handful of the multiple dozens of ways to do that and so the tutorial has that in there. The chances of those other technologies lining up with exactly what you know are probably slim so it makes you think that they are trying to teach more than one thing.

Another theory I have is that the writer looked at this new tech and thought it would be interesting to make a video on it. Oh and while I’m in the learning a new skill mode I’ll also pick up X. Now X is top of mind so it leaks into the original presentation.

Yes not to mention git and docker are now assumed.

The ability to use a VCS is a fairly reasonable assumption for a programming tutorial unless it is for complete beginners.

Hrm, agree, but the OP said some of these were written for complete newbies. A newbie at software development is not going to know what VCS stands for.

Agreed, but in many cases it's still an unnecessary detail.

I don't mind Github as much, esp if you're instructing people to download a zip, unpack it, and start there.

Those are pretty powerful ways to learn. With git, you can jump branches pretty easily as you proceed through the steps of a tutorial (either for the student or for the teacher to provide some assets for that step)

Docker allows a packaged environment without having to install a bunch of dependencies, and easily shut down/remove those environments.

They are absolutely the most awesome things, and I couldn't go back to coding without Git and I am almost at that opinion with Docker. However as a beginner it must be daunting.

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

Steven Pinker calls it the “the curse of knowledge”. I noticed the behavior at the university, many professors seriously underestimated the amount of time required to learn chemistry or the lack of background most students had on what is “common knowledge” among students.

The authors believe that their audience already knows most of their vocabulary and are familiar with the same technologies. Additionally, authors underestimate the amount it takes to learn something they are familiar with.

Pinker believes that this behavior results in bad prose, by extension tutorials of poor quality.

Popularity is King.

Even if the Python solution is vastly superior, there is significantly more people who know or want to learn Javascript, so if your game is to sell stuff, it's only reasonable to pick the bigger market, and the kind of complexity you're talking about is very common to modern Javascript.

Most devs know some Javascript and as complex as the current js ecosystem is, it still seems like those devs would prefer to deal with some libs in a language they already know rather than learn a completely new one.

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'm working on a Kubernetes course

Could be useful. Kubernetes is written in Go, so it fairly reasonable to expect them to have some clue with that language.

> I've settled on a smallish Rails app...

Huh? Well, I guess if your course is designed for people moving from Ruby to Go, then it'll be a good fit. For everyone else though, it sounds like you're adding a second language to the need-to-know list for prospective students. :(

The course is on using Kubernetes, not extending it. I'm unclear where you'd ever have to write Go.

That said, I should perhaps be clear that my course is geared toward someone who is already a developer, they just need some sort of an app to deploy to give the course any value. In my case, I chose Rails. I'll just give them the code, but do a side-course walkthrough if they are interested.

Consider offering the same app in multiple implementations. Focus on the "why" and not "how". The how part becomes much easier to communicate when the students understand why it works.

The most frustrated things I found with nowadays tutorials is misguided prerequisite. If you read prerequisite of tutorials, you might read that famous word - "for absolute beginners" but then they throw 40 lines of program in features introduction.

The main thing we must have to fix is - "truth about prerequisite" Its okay to have different target audience than absolute beginners.

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

Because they are not good teachers.

It's much the same on sites like Quora where a question that is answerable in a single line gets half a dozen answers each of which drags in pages of irrelevant material and in some cases actually fail to address the question at all.

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.

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.

Simplicity is very hard.

There's a reason pedagogy is a field of study.

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.

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.

No one writes a tutorial to teach others, at least not for free on the internet. The real purpose is to signal their own expertise (even if they know nothing more themselves than what is in the tutorial).

You see a similar dynamic at work with business gurus giving out free investment advice, ask if they knew so much why aren’t they successful investors themselves? Or middle-managers on LinkedIn handing out their “leadership” technique.

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

Bingo! This is not all of it, but it's a big part.

This is being on the other end of the common internet career advice of "write blog posts to set yourself apart".

Reply on news.ycombinator.com