Why are code tutorials so terrible 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. |
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.
I've seen this in tutorials, but also in open source project's documentation