
Why Programming Tutorials Are So Hard to Understand - taphangum
https://fromtoschool.com/why-most-programming-tutorials-are-so-hard-to-understand-and-a-solution-to-this-problem/
======
ksaj
I think another problem is that there are too many people _learning_ a
language while simultaneously writing tutorials. Maybe its an ego thing, but
it nearly always leaves behind a tutorial full of mistakes and bad practices.

For example, search for Common Lisp tutorials and you'll find dozens of
unfinished ones - many pretending they are manuscripts for books that will
never end up being published. It seems that they get far enough into their own
tutorial that they discover their prior errors, but were too lazy to go back
and correct them. Add the word "Quantum" to the search, and you'll get nothing
but utter crap in terms of tutorials or even basic information, because it is
the people just learning about the subject, and passing off their personal
learning notes as authoritative information when they are literally the
musings of a beginning student.

So there is a tonne of garbage out there that is either unfinished, or written
by people who didn't know the language at the time they were writing the
tutorials, and didn't bother revising their work or having it reviewed by
people who actually do know the subject matter.

That's 99% of the Common Lisp, and 100% of the Quantum Lisp tutorials out
there, anyway. Shove a tut out and then hope for accolades as if you are a
real author and educator - great for the resume, and terrible for everything
else.

~~~
taphangum
Definitely agree with this. It's something that I have actually been guilty of
in the past myself.

------
pmdulaney
This is such an important topic. What I do when learning something new is
create a Word or vim file to document my own learning process, filling in the
gaps left by the tutorial as I go. That document becomes my own personal
tutorial.

People who write tutorials will counter: "You can't teach EVERYTHING -- you
have to assume some knowledge!" Which is true, which any parent who has
endured an infinite chain of "why" questions from a child can attest. But most
online tutorials could be MUCH better than they are.

I've come to the conclusion that the reason most tutorials are so bad is
because -- unlike myself -- most people who write tutorials don't like
teaching. They think it is a distraction which takes them away from their
"real" work. But I would challenge those who write tutorials: Create a work of
art! Good documentation is something to be proud of.

~~~
taphangum
Amazing comment, and I totally agree! I am actually one of those people who
never used to like making tutorials. What changed my mind ultimately was
gaining an understanding of just how impactful they could be.

Good documented can indeed be a work of art, and is the first port of call for
anyone who'd like to engage with your technology. Why would you not want to
take that seriously?

