Why are code tutorials so terrible

[highiquser]

Do the people who write the tutorials actually consult with the people who want to use the code? It is like every time I want to code something simple, the guides always have tons of superfluous stuff. Most end users have simple needs, so have tutorials for those. Consult end users and ask them what they want.

[jarcane]

I think the fundamental problem with teaching code is that teaching code is not math, it's language, and language is quickly internalized once you 'get' it.

Most of the people who write books and web tutorials teaching code already know the code, but don't realize the extent to which they've internalized a large amount of understanding of the subject. So what makes perfect sense to them either gets dropped on the table without explanation, or struggles to actually give a clear why of the thing. Being able to recognize that, and explain those things clearly, is a very specific skill in programming just as it is in language, and just as sometimes language classes get given to someone who just happens to speak the language rather than who is a linguist, you will often find someone who speaks, say, Java or C++, but can't necessarily explain clearly why or how the patterns and techniques they've internalized work.

I'm increasingly a believer in more interactive methods of code teaching, because I think like language it's a subject that requires immediate practice to facilitate that internalization. Exercises like the Codecademy courses, or the Koans, which pair explanation with specific examples, immediate practice with new concepts, and equally immediate feedback about failures/successes, do a far better job of teaching a language than anything else I have seen.

[singold]

I think that sometimes the devs writing the tutorials, didn't bothered trying out the tutorial themselves, so there are little errors that are huge for beginners.

I've seen this in tutorials, but also in open source project's documentation

[Randgalt]

Tech writing is a specialty. It's a different skill set than coding. Unfortunately, it's the devs who write the docs these days and they're not usually good at it.

[wturner]

I was thinking about how it would be kind of nice if their was an official equivalent of a W3C guideline list for teaching programming. Simple things like "start with a working script that your student can experiment with which includes no unnecessary code. Then work backwards to explain how the code works."

[jhwhite]

I think it depends on the tutorial. Michael Hart's Ruby on Rails tutorial is pretty awesome.