Rewrite the intro tutorial

[brson]

We have major questions about how to best present Rust: as the language
has evolved it's character has taken shape, but how to express its
unique strengths in a cohesive and compelling narrative is still
elusive. A great writer should be able to unveil the language gradually,
leading the reader to understand why Rust is powerful, and to understand
which patterns will lead to success. That last point is very
important: many people come to Rust, try to apply the patterns they are
familiar with from other languages, and become frustrated. It's critical
that we show how to be effective in Rust. What is "the philosophy of
Rust" and how should it be taught?

[brson]

Nominating.

[brson]

We'll probably contract this work.

[catamorphism]

1.0, high

[LeoTestard]

This is a very interesting issue to me (programming teaching is a topic i'm quite interested in... ). If I had a better english level, I would probably try to work on it. By the way, I intended to write French documentation about Rust. Or maybe just a translation of existing english documentation. If there is interest in it... I dont know...

[adrientetar]

@LeoTestard @sinma is translating the official tutorial into french.

[ariasuni]

@brson: «many people come to Rust, try to apply the patterns they are
familiar with from other languages, and become frustrated. It's critical
that we show how to be effective in Rust.»

Totally agree. I didn’t know how to use Rust to do things I was doing with in other languages (mainly with inheritance).

@LeoTestard: At the moment, the French translation of the main tutorial is (a little bit more than) 10% complete. I didn’t plan to translate others tutorials because it eat my time, and I’ve so many personal projects and so little time. ;) So contributions are always greatly appreciated.

Speaking of document in other languages than English, I’ve also published a news on Linuxfr.org about Rust, which might be published on the wiki of Lea-Linux soon. I think most of it can be understood by beginners.

[LeoTestard]

@sinma I'd like to contribute to this translation. Do you have an online repo or something for it ?

[ariasuni]

@LeoTestard: https://github.com/sinma/rust. I word on the «doc» branch. I’ll be busy soon but I’ll try to translate bit by bit.

[brson]

Some mailing list discussion: https://mail.mozilla.org/pipermail/rust-dev/2013-November/006633.html

[adrientetar]

@thehydroimpulse I think you are confusing with #9875.

[thehydroimpulse]

@adridu59 Oops, Yeah.

[puredevotion]

I've read quite a few introductions and tutorials over the last years, but I've found the Python tutorial by far the best.
It reads easily, lightweight, is thorough and provides a quick tour of the major features of the language. Concerning optimal patterns, the File I/O chapter (http://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files) has that well covered. I can distinguish for developers who've read that chapter, and those who haven't.

The last tutorial that I've read was that of Go (Go Tour). Wasn't impressed. Dry, unimaginative examples and I felt (but very personal) that the Gopher icon was some forced "lightness/humour".
But I do like that after going through some features, there's a small code example that applies those features. I'm a huge fan of learning by example.

I found this: http://paulkoerbitz.de/posts/Understanding-Pointers-Ownership-and-Lifetimes-in-Rust.html to be a great read. I haven't used pointers in ages, and this was enlightening.
Developers coming from dynamic languages (or non-pointer languages. My Java experience didn't really do it for me) might have some issues with the general idea of pointers.
A stupid example is that the term dereferencing isn't introduced in the tutorial for example. Maybe a short introduction to pointers, referencing and dereferencing would be a good idea as it seems that many Pythonistas among other are looking curious at Rust.

Lastly, maybe add an index of 3rd party tuts and intro's. If someone doesn't like the writing style, or wants a simpler or more thorough introduction, he can easily find one if available.

[darnuria]

Hmm maybe we could use SF and Paris Futures meetup to try working on it? Or it is better to focus on general documentation during meetups? Hmm? Any Idea?

[brson]

@darnuria At this moment I suggest not working on the main tutorial since I am hiring a contractor to focus on it - once that contract gets up and running he will probably start soliciting a lot of opinions on the mailing list etc. All the guides and other documentation are fair game.

[steveklabnik]

Today, I am starting on this!

For anyone else who wants to contribute, see this reddit comment: http://www.reddit.com/r/rust/comments/28bew8/rusts_documentation_is_about_to_drastically/ci9c98k