[jimmoores]

Great to have a resource like this. By way of providing some hopefully constructive feedback, the language seems a bit excessively informal: "Safe Rust is For Reals Totally Safe. Unsafe Rust, unsurprisingly, is not For Reals Totally Safe. In fact, Unsafe Rust lets you do some really crazy unsafe things". I get the idea that's it's trying to be friendly and street, but it's a bit out of place in a document like this (I was just waiting for 'shizzle' to pop up). There also looks to be an excessive use of emphasis (italics).

[Gankro]

Haha, yeah I like to be a bit silly here or there. I might tone it down, but on the other hand I find it makes the text a bit less dry to not take yourself too seriously. :)

re italics: https://github.com/rust-lang/rust/pull/27414

[unfamiliar]

I see what you are aiming at, but honestly this informal style is hugely irritating to read for me, and is probably the main reason I haven't delved further into rust - I just can't spend more than 5 minutes reading the guide. It seems like it takes twice as long to get the information across because there are constant "quirky" remarks, weird and anthropomorphisations of computers or code, or "humorous" observations about coders. I agree the italics are annoying; there really isn't any need to stress particular words, people can read and if you write well it will be pretty obvious which words are supposed to be emphasised ("really" really doesn't). In general the tone comes across as a mix between cocky and patronising ("this book contains invaluable information" - how modest).

For example, the two opening paragraphs basically told me nothing that the title didn't. And then we have things like this:

>With that said, Rust is totally a safe programming language.

What the hell kind of a statement is this to put in an advanced programming book? It adds nothing, sounds childish. Just let the content speak for itself, stop trying to be relatable or funny.

Sorry if I'm coming across as bitter and whiny, but I am disappointed that this is suffering from the same problem as the guide for me. I honestly think it would be good for the project to have someone else to be writing these guides.

EDIT:

> Safe Rust is For Reals Totally Safe.

> That's totally awesome.

> Low-level programming cares a lot about data layout. It's a big deal.

> TODO: ALL OF THIS OMG

cringe...

For some constructive criticism, I think Julia's docs really hit the right mark. Here is their introduction: http://julia.readthedocs.org/en/release-0.3/manual/introduct... There is a lot of information on that page, a clear mission statement, not too dry but still manages to speak to you like an adult.

[muraiki]

I guess there are at least two schools of thought for programming books. There's the one you mention, and there's a different approach that you'll see here and in other books like Learn You a Haskell for Great Good, Brave Clojure, and perhaps most famously, why's (poignant) Guide to Ruby.

I think that there's a place for both of these styles in the world. And perhaps this style can appeal to a person who struggles with the stereotype of computer programming as a serious, dry affair, bereft of human expression, the job of coder cogs in programming factories. Perhaps you could say that the serious style appeals to more people, but maybe that is actually a criticism of the population of programmers, and not of the work?

In regards to sounding childish, I find that in general to be an unusual criticism. Perhaps there are people who speak this way as adults simply because that is who they are? I guess C.S. Lewis sums up my feelings about "being childish":

Critics who treat 'adult' as a term of approval, instead of as a merely descriptive term, cannot be adult themselves. To be concerned about being grown up, to admire the grown up because it is grown up, to blush at the suspicion of being childish; these things are the marks of childhood and adolescence. And in childhood and adolescence they are, in moderation, healthy symptoms. Young things ought to want to grow. But to carry on into middle life or even into early manhood this concern about being adult is a mark of really arrested development. When I was ten, I read fairy tales in secret and would have been ashamed if I had been found doing so. Now that I am fifty I read them openly. When I became a man I put away childish things, including the fear of childishness and the desire to be very grown up.

[unfamiliar]

I agree that there is a place for both styles in the world. Unfortunately when it comes to rust most of the tutorial seem to be in this style, and I thought at least the "advanced" guide would be more "sensible". I enjoyed Learn You a Haskell, but that was an introductory text. If I am reading an "advanced" text on a systems programming language I probably expect it to be a little more formal.

>In regards to sounding childish, I find that in general to be an unusual criticism. Perhaps there are people who speak this way as adults simply because that is who they are?

First off, maybe it wasn't the best word for me to use. However, the second statement is a tautology; of course if they are childish then that is "who they are": childish people. The term to me doesn't denote an interest in "childish" things, like the CS Lewis quotation seems to say. Rather it denotes "not fully emotionally developed" which is usually a judgement placed on their current behaviour. You can read all the fairy tale books you like, I don't care. But if you start exhibiting the negative behaviours typical of children - selfishness, irresponsibility, etc - then yes, you are a bad person and deserve to be called out for it. (I'm not suggesting this at all about the author - this is now a separate discussion.)

[muraiki]

I was reluctant to quote Lewis because there is more context to his ideas than can be conveyed in that quote. The negative behaviors you describe aren't typical of just children: they are typical of all of fallen, broken humanity. It's just that children are more honest in being direct about those negative behaviors. :)

Since we associate these negative behaviors with "childishness," we risk throwing out the good with the bad: we lose imagination, wonder, honesty, playfulness, etc.

I realize that you aren't suggesting the author has those negative behaviors. I'm only trying to provide a greater context to Lewis' quote. Perhaps I should have just stated this argument on my own; I apologize for any confusion.

[SyneRyder]

Curiously, this feedback is actually making me interested in reading the Rust book. I enjoy humour and personality and wish there was more of it in business, as long as it isn't forced. (I've not read the full guide/book yet to see if it tends more towards personality or forced.)

Looking at that Julia example, I find that far too dry and academic. (The presentation is great though, better design.) For a scientific computing audience it's probably ideal, but that isn't for me.

[Sirenos]

You're not alone. On flip side, however, there are people who prefer a more informal tone and find academic treatments a little dry. I guess you can't win in that regard since someone else is bound to find your book/guide unapproachable due to whatever subjective reason they have.

That said though, I don't see why an informal tone should preclude getting the information across and sprinkling in some humor -- all without sacrificing precision. Something like Bjarne Stroustrup's C++ book is a good example of how to retain both humor and a thorough treatment of the subject.

[topbanana]

FWIW, I agree with the previous commenter. It also makes it harder to read for those whom English is a secondary language

[AndrewDucker]

It makes it more fun for me to read - but significantly harder for anyone for whom English is a second language.

(I'm currently rewriting a bunch of internal documentation for offshore workers, and anything which complicates the language or is a reference to culture is being taken out, because it's just confusing to people who don't share that with you.)

[Gankro]

Also RIP this intro: https://github.com/Gankro/rust/commit/a42a41520584e28a8fb5e4...

(one of the many reasons I refused to squash this glorious history)