21–30 of 80 posts
personally, I feel I learn best when learning from examples and changing them to experiment with them and find out how they work.
Most tutorial writers are 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."
My theory is that exposition is hard. Most people are shit at teaching.
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...)
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 just ran into this right now. Wanted to see how to do something in CSS and they had it all nicely split up with combining classes as if I was working in a shared code base. I really just want to see HTML with inline styles so I can see where to put what and not have to chase down referenced sections and mentally combine them as I go. I know how to use CSS classes vs styles but that's not what's being demonstrated here.
It can go the other way too though. Sometimes with a certain framework they only have an example in either MySQL or PostgreSQL and it's really hard to find the alternate example. Sometimes it's simple, but other times the names/versions and way to load the drivers are different. One back-end framework's most popular tutorial uses a dictionary in memory as it's model. I think using a DB is a fairly standard requirement. I didn't just want to use it for routing. To be fair, the back-end is pick-and-play, but a good tutorial should just pick one of the typical ones and go with that.
Most 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."
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).
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.
That's not teaching, it's boasting.
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 els…
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 h…
> 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 insta…
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 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.