
Ask HN: Why do tutorial writers combine 10 technologies when 1 or 2 would do? - akudha
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&#x27;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 (&quot;no coding experience necessary&quot;) 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).<p>Isn&#x27;t this crazy? I can understand paid courses doing this - maybe they think they&#x27;re providing more value for the money by tacking as many tech as possible, but free resources? Even they do the same!
======
tedyoung
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...](https://www.youtube.com/playlist?list=PLBHctPrH7Z2-BcpRWJ0uFanCbTHqdJ_1T))

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

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

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

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

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

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

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

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

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

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

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

~~~
hombre_fatal
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?

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

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

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

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

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

------
akkartik
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](https://en.wikipedia.org/wiki/Shuhari))
Makes the writer's job a little easier, but the students' job infinitely
harder.

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

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

~~~
justinclift
> 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?
:)

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

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

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

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

------
pascalxus
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](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.

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

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

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

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

------
quickthrower2
Yes not to mention git and docker are now assumed.

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

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

------
sixhobbits
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](https://github.com/sixhobbits/technical-writing)

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

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

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

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

------
bdcravens
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?

~~~
justinclift
> 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. :(

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

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

------
troutwine
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?...](https://www.amazon.com/dp/B07C5WXSXX/ref=dp-kindle-
redirect?_encoding=UTF8&btkr=1) [2]
[https://blog.troutwine.us/2018/06/07/hands-on-concurrency-
wi...](https://blog.troutwine.us/2018/06/07/hands-on-concurrency-with-rust/)

------
vkaku
Because they are not good teachers.

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

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

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

------
CareyB
Simplicity is very hard.

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

------
wiseleo
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](https://github.com/DiscoverMeteor/Microscope)
and the [http://discovermeteor.com](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...](https://developer.salesforce.com/docs/atlas.en-
us.api_rest.meta/api_rest/intro_understanding_web_server_oauth_flow.htm) 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.

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

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

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

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

