

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.

