Why Programming Tutorials Are So Hard to Understand

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.

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.