
Rethinking Programming Language Tutorials - Garbage
http://prog21.dadgum.com/67.html?0
======
wolfgke
Not all tutorials are aimed for people that know nothing about programming.
Many are intended for an audience that knows programming in a different
language quite well but doesn't know a lot (or nothing) about the new language
(in this case Lua).

For this kind of people it would be a waste of space to bring lots of
"practical" examples, if this doesn't show a unique feature of the language,
since people often know the algorithms quite well. If you want to learn about
that you better get a tutorial/book about algorithms.

What they don't know is the topics that are specific to the programming
language. IMHO it is right that many tutorials concentrate on this.

~~~
exDM69
Spot on. There is a difference between "Programming language X tutorial" and
"Programming tutorial using language X". The former being for someone who
wants to learn a new language (but probably knows some programming) while the
latter is for people learning their first language.

This article seems to suggest that programming language tutorials should
always be targeted at people with zero knowledge about programming or computer
science. And he also seems to suggest that all readers are assumed idiots.

In the OP's view, the description of associative arrays as a primary data
structure in Lua is not important. This depends a lot on the audience. For me
the description about associative arrays was very important, since I want to
know how the Lua interpreter works (esp. important for Lua since it's often
used as an embedded language).

Same thing goes for the OP's complaint about Haskell and laziness. Laziness is
a very central concept to Haskell so it makes sense to introduce it early on.

The OP says: "Programming language tutorials shouldn't be about learning
languages. They should be about something interesting, and you learn the
language in the process." I really disagree on this one. I don't want to spend
time going through yet another badly written beginner tutorial if I want to
learn a new language.

~~~
qznc
I agree with your distinction.

However, the paragraph from the Lua manual still shows sloppy technical
writing. Terms should be defined before they are used. Using another technical
term is not a good description. For example, coming from Python an
"associative array" would have to be called a "dictionary". For the Java and
C++ programmers it would be a Map. Better:

The table type provides storage of values under certain keys. Lua uses tables
to represent ordinary arrays, sets, records, queues, and other data
structures, in a uniform way. For example, a table can be used as an array,
since it can store arbitrary data under index numbers as keys.

~~~
exDM69
> However, the paragraph from the Lua manual still shows sloppy technical
> writing.

That may be true, but we just have to live with it. We can't expect every
piece of software to be documented properly (or even at all).

> For example, coming from Python an "associative array" would have to be
> called a "dictionary". For the Java and C++ programmers it would be a Map.

I think the term "associative array" is used here (as well as in PHP docs)
because it's distinct from Python-style "dictionaries" or Java/C++ "maps" in
that it's the only data structure used in Lua. There's no lists or sets like
in Python. I think this is the intent that the manual wanted to portray.

------
exch
I understand where the OP is coming from, but I will go one step further.

If you are teaching programming to someone who has never written a line of
code, you need to do away with the programming language all together. When you
start out, you are learning two distinctly different things at once:

    
    
        * General programming principles; abstract thought patterns.
        * The language it is being taught in, along with all of its oddities and quirks.
    

These two do not mix very well and can, in some cases, be counter intuitive. I
believe that teaching someone to /think like a programmer/ and learning
analytical and iterative problem solving are of primary importance. They apply
to any language. Once you grasp these, the actual language of choice is
considerably less difficult because patterns in the language are immediately
familiar.

I'm fairly confident that you can effectively teach someone to /think like a
programmer/ without ever showing them a single line of code.

~~~
JabavuAdams
This doesn't work well, in my experience. Non-programmers don't want to
program -- they want to get a computer to do something. As a teacher, it's
your job to seduce them into programming as a way to get the computer to do
what they want it to do.

I learned to program, not because I wanted to program in the abstract, but
because my friend's dad showed him how to make a little car drive across the
screen, and I wanted to do the same.

I spent hours typing programs in from books, not because I wanted to program,
but because I wanted to get 3d shapes moving around.

When I taught programming classes, I'd often digress to talk about some
interesting abstract concept -- and immediately lose 90% of the class. Start
practical, and enrich from there, as the material becomes relevant.

~~~
trustfundbaby
I came here just to agree with this ... I took Computer Engineering in
college, did quite a bit of C++, Assembly programming and Data Structures ...
but I really didn't 'get' any of it, even though I could pass tests and ace my
finals. It wasn't until I happened on a PHP tutorial that showed how you could
post user information to a db and replace a section that once said "login"
with "Welcome xxxx" that it all clicked. My brain started to go crazy with
possibilities and I immediately started trying to learn EVERYTHING about
programming.

I spent hours on Sitepoint, printing out articles and just reading them over
and over, and trying them out. (I still have the huge stack of printouts in a
section of my home office as a reminder of all the work I put it ... you know
... when I start to doubt myself). I had learned OOP in college but I really
didn't get it ... one day I went to Barnes and Noble and spent the whole day
reading a Head Start OOP book ... and I 'got' it. I felt like Neo in the
Matrix (I know Kung Fu!!!)

The point of the story is ... keep all the boring crap out of the way at
first, get beginners excited about building things, that will give them the
passion that will carry them through the (necessary) minutae later.

------
jsvaughan
You can get it the other way round though. I don't have it to hand, but I
found "Programming in Scala" to have such a low content-per-page ratio that it
is hard to stay interested. From the contents page:

2\. First Steps in Scala 69

3\. Next Steps in Scala 82

4\. Classes and Objects 104

100 pages and you're only onto classes and objects!

Dive into Python has it right, IMO - show you something, then explain it bit
by bit.

~~~
gaius
I co-authored a book published by Wrox Press a few years ago. Editors
specifically tell you to pad as much as you can - the fatter a technical book,
the better it sells apparently.

~~~
daniel_solano
That's an interesting observation. Not long ago I was talking to an editor who
thought that books 150-250 pages in length were an ideal sweet spot.

~~~
dagw
Back when I was young a naive and just starting out this wonderful world of
computers, my default stance was, when in doubt buy the thicker of the two
books since it must contain more information. I distinctly recall standing in
a book store and working out which massive Linux book would give most pages pr
dollar.

Now my default stance is, when in doubt, buy the book that's under 300 pages,
since if you can't cover you're points in less than 300 pages you're either
trying to say way too much or your book is mostly fluff and filler.

Also I imagine the ubiquity of fast internet connections and Google has made
the 1200 page "complete reference to everything" type of books more or less
obsolete. More and more books these days are "focused expert knowledge in one
particular area" which is a lot more suited for the 150-250 page format.

------
EzGraphs
It depends on your intended audience. Although I appreciate the sentiment of
learning programming languages by solving practical problems (rather than
reading overly abstract descriptions) I don't expect there to be a major
change in the way tutorials are made.

Back in the day when java was just being introduced, nearly every tutorial
presented it in terms of how it compared to C++ (presence of garbage
collection, use of references rather than pointers etc.). This is because
languages don't live in isolation, they are part of a larger tradition. Java
was created to address certain problems and short-comings of C++ and the
target audience was therefore C++ programmers.

Most folks that I know who have become programmers made a concerted decision
to accept the discomfort and pain of pushing through the challenge to picking
up the nomenclature used by the programming community. I certainly appreciated
tutorials that were geared for beginners when I started, but - in the end -
simply immersed myself by reading so many different books and tutorials that
the short-comings of one were overcome by the other. Terms that were left
undefined in one were explained in another. There is certainly some
responsibility for the person creating the tutorial to clearly define terms
and consider the beginner. There is also the responsibility of the learner to
accept their ignorance pursue answers outside of the presentation of an
individual tutorial.

------
heydonovan
We need more interactive programming tutorials. Things such as TryRuby,
Codecademy, or VIM Adventures. I've never met anyone who actually enjoyed
sifting through static text, trying to make heads or tails of what arrays or
void pointers were. That's boring, and really disheartening.

When I was teaching my girlfriend HTML, she had absolutely no interest in what
a tag was, or why it even mattered. She could care less about semantics,
mobile design, etc. All she wanted was to create something on screen. After
having her use the inspect tool from Chrome, she found it more interesting,
and could see values changing. This held her attention for a longer period.

Till this day, the best tutorial I've ever read is _why's guide. I've read it
several times, because it's super interesting, and extremely entertaining. If
more programming tutorials were written this way, I'd be one heck of a
developer by now. Why can't authors make their tutorials fun? What's stopping
them?

------
krollew
I disagree. Early mentioning "associative arrays" is a problem? I don't think
so. Even if reader don't know what they are, he can learn from wikipedia or
somewhere else. Why write so many times about basics? Googling is so hard?
Sory, I think it's most basic programmer skill - to find information he need.

The same with everything nil and another novice caring stuff. This book is
good (I know since I learnt from it), if authors cared about so-novice-people
this book would suck so much. Imagine you want use lua for your C program,
whant to learn it first and you read what associative array is. I'd be mad.

And I disagree with your point about "practical" examples. Practical stuff you
learn at work. Examples are good to learn syntax and general stuff, rest you
can find quickly in documentation.

On the other hand, programming tutorials needs rethinking, but I think it need
far deeper change.

~~~
andrewflnr
There will be plenty of time for the new programmer to get their google-fu
from reading other people's crappy documentation. As a writer, though, it's
your job to make your piece as useful as possible for your _intended
audience_. This means practical examples, because that's often the best way to
learn in this type of scenario.

The point about PiL is not that it's a bad book, it's that it's a bad
introduction for a non-programmer. PiL was extremely useful to me when I
already knew C++ and Python, but I can also see that if it had been my first
programming resource I would have been in trouble.

------
blatherard
I'd recommend looking at "Learn Python the Hard Way"
(<http://learnpythonthehardway.org/>) for an awesome example of a tutorial
written with teaching beginners in mind, rather than the typical uncomfortable
combination of teaching and documenting that happens in most tutorial books.

------
JabavuAdams
Er, how about we have different books for different audiences?

The Lua programming book isn't a tutorial, as far as I can tell. As an
experienced programmer I appreciated its brevity and spare clarity -- it
mirrors the language. Adding words would make it significantly less useful to
me.

------
Lockyy
I completely agree with him, the best tutorials I've ever had for languages
were ones that had me make something I might use.

My first experiences were in c++ and that had me making little games in the
command line. I eventually took it upon myself to write an implementation of
conway's game of life once I learnt about 2d-arrays and realised I could use
two of them to make it.

Visual studio 2010 has a very nice set of tutorials that I found really great
for learning c# with. The first was just a program that had 3 buttons (open,
clear and close) and a picture box. It just opened an image and displayed it.
It was a really nice tutorial that was fun, taught fast and inspired me to
make the first program that I actually use on my desktop. It's a pretty basic
slideshow program, but I've never found one that fitted what I wanted and the
tutorial gave me all the tools I needed to create it with, nothing more.

That tutorial made me sit for a weekend and write that program. The feeling of
finally having a program that did what I wanted and the fact that I made it
just added an extra level of joy. It really showed to me why programming is
enjoyable.

The quality of a tutorial for an absolute beginner can make or break their
motivation to ever try again. It's far too important to not do well.

------
marijn
I tried to write <http://eloquentjavascript.net> with this in mind — building
from basics, driven by actual examples.

~~~
sireat
You probably get told this every day, but your book is awesome.

Well spaced English, good examples.

------
frobozz
I agree. I think this approach allows the tutorial to be useful regardless of
other language programming experience.

If you are new to programming reading a tutorial aimed at experienced
developers, then, as OP states, it can be difficult to understand paragraphs
loaded with unfamiliar technology, or where the concepts are presented in an
entirely abstract fashion.

If you are an experienced developer reading a beginners' tutorial, then it's
easy to miss some crucial novel detail hidden amongst all the bits that you
already know.

If the tutorial takes you on the journey from a blank text file to an
application that does something, then all levels can be as engaged as they
need to be.

On the other hand, it will be just as easy to make a rubbish tutorial in this
way, as it is to make a rubbish one that teaches the language in a more
abstract fashion.

------
AlexBlom
Agreed. As somebody who has self-taught / is self-teaching, many of the guides
become very complex very quickly. I'm fine with that now. At the start it was
a frustrating experience, and I'm one of the people who wikipedia's everything
he doesn't know.

There's no problem with books set for different levels. In-fact, I hate those
beginner books now as they move too slow. The issue I see is most publishers
incorrectly bucketing their guide as beginner-level, and either going too deep
too fast or writing code without explaining the mechanics.

I've seen many people get frustrated, lost and give up as a result. You can
argue they didn't have the mind / passion for this type of work, however I
observe many people who stop before they get started.

------
jmsduran
In my opinion, the problem with programming language tutorials (especially
those found on the web for free), is that many are written by people who are
not that great of technical writers, and even less so at keeping the reader's
attention.

The best programming books/tutorials I've read motivate the reader to ask
questions and perform hands-on experiments, all while being as accurate &
comprehensive as possible.

Language tutorials do not need to be dull walls of text, that's why I'm a big
fan of the "Do X while Learning Y" tutorial style, and am glad whenever I see
a good one pop up on HN.

------
mingfu
I've been teaching/tutoring people on how to program since my high school
days. One of the best tools I've come to rely on is being able to show my
student what the end result of the program looks like and how it behaves. Its
often much harder for people to realize what you are trying to do with
specific lines of code without having seen what the end goal is. Having seen
the final result and working backwards along side you to figure out the bits
and pieces that would be required to make the end result work is something far
easier and more natural for people based on my experience.

------
eblume
I'm sure this isn't a new thought, and I will also admit I didn't finish the
article so this may have been brought up, but I strongly consider 'teaching
someone to program' and 'teaching someone to program using language X'
completely different topics with very little common ground that must be taught
using entirely different methods.

The first few paragraphs of the article point out problems with some
tutorials/manuals for languages getting too deep too fast, but I like that
feature now that I know (in some manner) how to program.

------
goldmab
_If you want to learn to play guitar, the wrong approach is to pick up a book
about music theory and a chart showing where all the notes are on the
fretboard._

I found music theory knowledge very helpful when learning how to play guitar.
In fact, if somebody knows what intervals a minor triad and a major triad are
made of, and they know what note each string of the guitar is, then they can
work out how to play a _lot_ of chords.

~~~
andrewflnr
Did you already know an instrument?

~~~
goldmab
Yep. I learned music theory in the course of learning to play single-note
woodwind instruments. There's a lot of focus on scales and intervals.

------
Lewton
imo, Learn X The Hard Way does this exactly right for people completely new to
programming.

~~~
uniclaude
I absolutely agree. Every time someone around me wants to start programming, I
introduce them to Zed Shaw's books, and none of my friends disliked the
experience. His pedagogy is lightyears ahead of most technical books writers.

On the other hand, it's good that some books do actually target people with a
programming background, but this is not really a problem anymore, since those
people know where to find good books. Stackoverflow threads about books are
here for that.

------
bard
I completely agree. Learning to program myself, and pushing beyond the initial
jargon barrier is painful. I keep looking for practical tutorials, but they
don't really seem to exist. I want purposeful, hands-on learning. Without that
in the beginning, there's nothing to attach the theory/knowledge to and it
falls out the other ear. Show me what these things do and my brain will want
to do it!

------
ttt_
I believe that when you set out to learn something, the onus is on you to find
the best ways to appropriate the knowledge. Do not expect knowledge to be
imparted onto you, it's your role to reach out to it. A lot of the time it
will be a painful and exhausting thing, but that's natural.

If you set out searching for easy learning, you'll only get frustrated and
limit your options.

------
hluska
At the risk of sounding like a jerk, I notice that the author focused on Lua
and Haskell. While I think that both Lua and Haskell are useful languages, I
think they are rather poor choices for beginners. Consequently, I think that
the people who wrote the tutorials deserve the benefit of the doubt - I
somewhat doubt that they wrote their tutorials for complete newbies!

~~~
andrewflnr
Haskell I understand, but why do you think Lua is a bad choice for beginners?
It seems ideal to me: simple but fairly powerful, with little to no historical
cruft. Do you have some experience with watching new programmers figure out
Lua?

------
eslachance
This is why I really like Udacity's classes. Even though I have used Python in
the past, starting from scratch and building a small search engine is awesome,
and bits and pieces picked up along the way are really helping my
comprehension of the language.

------
naveen99
Just look at the manual for authohotkey, for an example of how to teach to
nonprogrammers. Hello world in ahk: !h::send, hello world Will type hello
world in any editable area in any application on alt +h Amazing feeling for a
non programmer.

------
nsomaru
I first picked up "C++ for dummies" when I was 12. I really tried and
struggled, but they didn't really explain much.

Ended up dropping C++ and learning Python years later.

