Hacker News Reader

Comment by wolfgke | Hacker News Reader

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.

View on HN

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.

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.

> 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.

When I look to learn a new language (knowing a few already), there are two things that I want to get out of the tutorial. I want to be presented with syntax and I want to be presented with what constitutes an idiomatic use of the language. If these two points are explained well, I should come away with an idea of the philosophy of the language, as well as tools to avoid common pitfalls. I should also be able to read other people's code in that language. Everything else can be covered by good documentation.

When I was learning to program for the first time, however, all that I wanted was a bunch of short programs that I could type in and make small changes to. It's hard to learn about a language's philosophy when you're spending so much time hunting for missing punctuation. At that point, you're just hoping that your program is going to do something.

With this in mind, I think there's a lot of room for improvement in both camps.

Agreed that tutorials on 'how to program' are and should be different from tutorials about a new language for experienced programmers, but one thing that both should do early on is a complete 'Hello World' example to show the minimum of code and compile/run steps required to run the simplest example. Too many tutorials skip that step and leave many of their readers unable to run the tutorial code at all because the authors haven't bothered to describe how to get a simple program to run. Those are obvious after you've done it once but completely unobvious to the people who read tutorials to learn a new language.

Yes, exactly. We need tutorials for people who are primarily learning to program and are using a language for that, and tutorials for people who already know how to program and are using a language for GST.

Reply on news.ycombinator.com