rust guide: Zooko finds some bits too fluffy

[zooko]

I've been reading the new Rust Guide. So far the chatty, informal, reassuring tone has left me waffling between being annoyed and being reassured, but mostly reassured. However, when I got to::

Programmers love car analogies, so I've got a good one for you to think about the 
relationship between cargo and rustc: rustc is like a car, and cargo is like a robotic 
driver. You can drive your car yourself, of course, but isn't it just easier to let a 
computer drive it for you?

The balance was tipped, and I became annoyed at the tone and started yearning for the old no-nonsense tutorial back.

So I suggest removing that paragraph, since it adds little.

[steveklabnik]

I specifically noted this, and nobody had any real objections at the time.

[zooko]

For what it is worth, I had the same “Ugh — too much cute!” reaction to:

A place for everything, and everything in its place.

[steveklabnik]

I'm not saying it shouldn't be, I just want to acknowlege that I wrote it, said "lol", and then shipped it with the intention of asking if it's too cute or not.

[zooko]

For what it is worth, I suspect the chatty and reassuring tone is great for a lot of readers, and I'm excited about the idea of making Rust accessible to the less experienced programmers (or at least, less experienced in the ways of low-level/systemsy/unixy tools), and I imagine this guide will work well for them. So, despite my grumpy comment about wanting the old tutorial back, I like this one and I'm glad you're working on it.

And I know that every reader has different bands of pleasure and tolerance for fluff. I'm noting the bits where I find myself becoming conscious of my own displeasure just in case it helps you tune it. I'm not commenting on all the bits where I found the fluff to be pleasurable.

[steveklabnik]

Absolutely. I think that being a bit lighter makes the docs way better than boring, dry ones, but I also recognize that it's easy to go overboard.

[chris-morgan]

Well, at least my crack about how cargo makes the car go didn’t get in! (That would certainly have been too much!)

[jnicklas]

I do like the fluffy tone for the most part, but this part threw me off too. Mostly because I don't get the analogy. How is cargo like a robotic driver? I don't get it. Analogies are risky in that while they can serve to enlighten, they can also confuse if the reader doesn't "get it". I think this one could be particularly tricky to understand for people whose English is not that strong.

Also "programmers love car analogies" is a bit of a generalization ;)

[MatejLach]

I think that the new Guide is way better than the old Tutorial was. See, it's a guide, not a reference, (we have the Manual for that). The Guide is meant to teach the reader about Rust and systems programming in an engaging manner, like a good book would. There's certainly a place for a more formal format as well, but that is what the manual is for.

Maybe it is because I haven't had much previous experience with systems programming, however the Guide is very accessible and this makes it easier for people like me to jump on the Rust train. I have some limited C++ experience, which is certainly helping, but the attitude that one has to know the old in order to learn the new is I think preventing many new programmers from trying some of these newer languages.

For a lot of people, it comes down to cost/benefit analysis: If I have to know C++ well in order to get into Rust, I'm just not going to invest the time into Rust but instead into C++, because of the much more established ecosystem. If instead I can jump onto Rust from e.g. Ruby/Python/JavaScript background as well, can learn at my own pace and don't have to first invest into C++ then I'm sold.

A lot of people adopted the dynamic languages precisely because they could be picked up from scratch and to be honest the dynamic people are one of the most active open-source communities here on GitHub, (Just check the amount of JavaScript pouting in every day) and if we manage to capture their interest the Rust ecosystem will greatly benefit.

Just look at Go, released less than 5 years ago and where it is today, thanks to the people coming over from Python/Ruby. I am not saying the Guide should be accessible to everybody, however it should be accessible to people without previous C++ experience and I think @steveklabnik does a great job at achieving this goal.

As far as the car analogy, well sure - not every analogy's so great, but that goes for a lot of books, TV shows etc. as well and I think as long as a point is made clearly, the particular analogy doesn't really matter that much.

[bachm]

Cargo is a tool that Rustaceans use to help manage their Rust projects. Cargo is currently in an alpha state, just like Rust, and so it is still a work in progress. However, it is already good enough to use for many Rust projects, and so it is assumed that Rust projects will use Cargo from the beginning.

Programmers love car analogies, so I've got a good one for you to think about the relationship between cargo and rustc: rustc is like a car, and cargo is like a robotic driver. You can drive your car yourself, of course, but isn't it just easier to let a computer drive it for you?

I find analogies are ultimately distracting and unhelpful. Rather than saying what cargo is like, it's better to say what it actually is. It's probably better to first explain what cargo is, before explaining that it's in alpha state.

[arcto]

Analogies are good only when they explain a difficult relation in terms of ordinary experiences.

In this particular case the relation rustc-cargo isn't very difficult to grasp and the robotic drivers image isn't ordinary or helpful - rather, it's a convolution.

[wackywendell]

I think part of the problem is that which every tutorial has: its adressing very different people at the same time.

Perhaps there should be two tutorials: Rust for "beginners" (anyone not too familiar with compiled languages), and Rust for those with more "experience". I think the chatty, friendly language is great for beginners, but could easily be "distracting and unhelpful" for those already familiar with the basic concepts, if not with how Rust handles them. Just an idea...

[MatejLach]

@wackywendell Yeah, I think that's a great idea and we already kind of have that with the Guide being chatty and the Tutorial being not so chatty. So, perhaps instead of the Guide replacing the Tutorial, it could supplement the Tutorial, although that would require two pieces of documentation with a similar aim being maintained.

[wackywendell]

@MatejLach Yes, it has its drawbacks: it would require two pieces of documentation with similar aims; I'm not sure how that is best addressed. I wonder what our Documentation Master @steveklabnik thinks...

It is a tricky thing, though: beginners need to be taught with an understanding that these concepts are complicated, take time to learn, and are not simple; I think the current tutorial does that very well. More experienced people see things like type systems and pointers as obvious and simple and feel talked-down-to when those concepts are given too much time and treated too simply for their tastes.

Perhaps its more like a 2-part tutorial, where the "beginner" section leads into the "experienced" section, and at the beginning, there is a suggestion that those with more experience may want to jump to Part 2? That still has its drawbacks, as you have to balance between covering everything in the right place for each group and trying not to repeat yourself, but maybe...

[MatejLach]

@wackywendell Perhaps it doesn't have to be 2 part, but having a piece of JavaScript where one could click on a "Background" tab next to problematic sections (e.g. pointers) and have a little bit of a background info on pointers unfold, whereas the experienced programmers would just leave the "Background" tabs collapsed and flow with it as an advanced tutorial. This way you can have one Tutorial accessible to both camps, altrough I would too like to hear @steveklabnik's opinion on this.

[steveklabnik]

Here is my opinion and general plan: https://air.mozilla.org/rust-meetup-december-2013/

Anyway, I think that enough people not liking this is justification to remove it. Can anyone suggest something that should go in its place, or should we just axe the paragraph and be done with it?

[MatejLach]

@steveklabnik Based on the comments and the fact that the next paragraph explains what Cargo really is in the first sentence; "Cargo manages three things: building your code, downloading the dependencies your code needs, and building the dependencies your code needs.", I would just axe the analogy paragraph and be done with it.

Awesome Guide BTW.