Honest initial impressions from my quick glance. This guide is confused. It reads at times like an informal conversation... lots of exclamations. That's pedantic, the real confusion comes from the target audience. As a programmer, I want as little cruft as possible. Get me to examples and how this differentiates from C. As a non programmer, teach me the basics of types and logic.
From that thought, it's failing at both. As a programmer, stop talking to me informally and redefining types as one liners. As a newbie, you're explaining basic shell constructs as if I don't know, then trying to sum up strings in a one liner.
I know it's an early draft, and I know Steve is an awesome dude. My advice - figure out your audience or else break into two guides. Be terse with me, be overly explanatory to a beginner. This now seems to sway on both sides of that line, and likely will frustrate both groups.
I disagree. I like it a lot, particularly if "graded" as a first public draft.
I'll admit right up front that there is a lot of subjective bias here, different people learn in different ways and you will never please everyone. So I'm not saying you are wrong, just that the guide appeals to me.
In terms of the A/B split on target audience:
A - Newbs) I'd argue that teaching people to code is way, way beyond the scope of any document like this, so the most logical starting target is someone who codes already but maybe doesn't have a ton of experience and maybe it is in a language very different from the one the guide is presenting. I think this guide hits that target pretty well as a straight-forward read. There are nitpicky things that maybe could be better, but luckily online guides like this can be expanded and iterated on.
Obviously a newb isn't going to understand something like what a "closure" is inherently, but they have the whole rest of the internet to tell them that when they see the term in this guide and then google it to fill in the blanks.
B - Non-Newbs) As an experienced programmer I think the guide is actually pretty great if you use the nicely presented ToC/index at the front as the primary interface to it. Click a concept and boom, you're looking at some nicely formatted example code along with some text that you can probably just skip over completely or skim because you already know what a closure is (for example) and just want to see the syntax for Rust.
I remain a diehard Go partisan for now, but I think this guide is actually superior in a lot of ways to the combination of the "Go Tour" and "Effective Go" which, cute mascot aside, are a bit too much on the dry/clinical side for me as introductory material to a language.
Disclaimer: I've been writing programming curriculum professionally for the last three years.
I do agree that it falls into the pit you describe, but I disagree that it's the style that's doing it. I think the style is fine, although there are always people it could turn off (e.g., you, perhaps).
Here's an example of him falling into that pit, though:
> By the way, in these examples, i indicates that the number is an integer.
Ok, that's an important detail! You have to be reading _very_ closely to read that line. An expert will be skimming (as you say) and someone less less expert might not even realize how important that fact is.
If I had to list "Five Rust Facts About Integers and Variable Bindings," noting that you signal an integer literal with that "i" character would definitely be on that list! As it's written, it's emphasized no more or less than any other part of the text.
This is good criticism. If you have time, might you consider creating an issue? https://github.com/rust-lang/rust/issues Steve reads all of the ones regarding documentation, and most likely would find it valuable.
Thanks! That's just the first instance I spotted — there were a few dozen similar things I saw after skimming for 2-3 minutes. I'll post an issue if I find time.
This seems to be fundamental problem with programming texts. I was reading a couple of javascript books recently (eloquent javascript and javascript allonge) and I was struck by the sheer amount of background knowledge you needed to have.
Most of that I've picked up over the last 20 years, but not all of it (or else I wouldn't be reading the books) so I constantly felt like I was having something I knew explained to me in too much detail or having crazy new concepts thrown at me without enough context.
I mostly felt sorry for total newcomers, particularly as I realised most of my knowledge was historical trivia or workarounds rather than actual useful. Once I noticed the above, the amount of crufty irrelevances we have to deal with became obvious, and that's doubly true in JS for the browser.
My only constructive thought was to break things into smaller skippable sections. I personally would skim rather than skip, but advanced warning that the section would only cover stuff I thought I already knew would be helpful.
Mark Pilgrim solved this problem quite well in "Dive Into Python". He presented the working code first, at the beginning of each chapter ("diving in"). If you could read and fully understand the code, then you had no need to read the rest of the chapter. If there were only small things you didn't understand, you could skim to those sections.
This philosophy is stated pretty clearly in the beginning of the book:
You know how other books go on and on about programming fundamentals and finally work up to building a complete, working program? Let's skip all that.
2.1. Diving in
Here is a complete, working Python program.
It probably makes absolutely no sense to you. Don't worry about that, because you're going to dissect it line by line. But read through it first and see what, if anything, you can make of it.
It's a new language with some interestinf semantics than can be tricky even for those familiar with say C or Java or Python etc, so it's good that it's conversational -- it helps cater to both the new programmer and the experienced one in other languages.
The skipping of cruft part I can do by myself, using "vgrep".
This "skipping of cruft" because we're talking to "experienced programmers" is what makes Manfiles nearly useless, EVEN for experienced programmers, unless as a very basic flag reference.
Some manpages have quite helpful "examples" sections, eg. find(1). Usually, if they do, these sections are towards the end, which isn't necessarily the first place you'd look unless you knew that that was typically where they were.
Many manpages, of course, do not provide examples.
Hopefully some of the issues you're noticing will get fleshed out before the guide is officially linked from the rust homepage.
I do agree with you though. I felt the same way about the guide from the first time I read (parts of) it, and I know we're not alone. I've commented before about how it's impossible to nail down the target audience, but it seems overly informal as a replacement to the current tutorials, especially compared to the "additional guides" that were linked to at the conclusion of the tutorial which really got down to business quickly.
I've long been hoping that something like rustbyexample.com gets officially sanctioned and linked to from the homepage alongside the guide. As a small metric, the current tutorial is 942 to Hello World, the new guide is 1595 words, and rustbyexample.com is 239 words.
I usually get that visceral reaction from pronoun heavy instructional material. I haven't decided if it is just a personal hang up or not.
It's usually possible to omit pronouns and end up shorter, maybe at the cost of ending up a little dryer:
"Welcome to the Rust guide. This is the place to learn how to program in Rust. Rust is a systems programming language with a focus on "high-level, bare-metal programming": low level control, but with zero-cost, higher level abstractions. We really think Rust is something special, and we hope you do too.
The guide starts with a traditional "Hello, World!" program. Next a quick detour to introduce "Cargo", a tool for managing and building Rust programs and libraries. Then it's back to the language."
If the guide actually builds something, the last sentence there could say "Then it's back to the language, starting with the basics and working up to <thing that is built>."
I think the problem is that references and tutorials fill different niches. This is a tutorial, basically. Tutorials are conversational, intuitive, hand-holding walkthroughs. If you think you already know enough, you should be able to just skim the reference. References are to the point, don't hand-hold, and get the job done.
Most languages' official "guides" use a more-or-less informal tone, from my experience. I've not read through the Rust Guide yet, but I'd think this is a good thing, especially as most newcomers to Rust will be learning new concepts (its type system is very different from most languages, unless you're coming from the strongly typed functional world).
Even within the domain of informal writing, there's a lot of fat in this piece that should be trimmed. I think that's what's triggering your distaste. However, once that is removed, as I'm sure it will, the tone will improve dramatically, and I suspect you'll only find it slightly annoying.
My guess is that by far the most likely reader of this document is a noob to Rust with some degree of experience in other languages. To be safe we'll only assume basic programming experience. As a more experienced programmer, I don't mind seeing a few explanations of things I already know. From that perspective, this guide is a good compromise, once the technical issues are solved.
