Hello rust-dev, I would like to make a comment I feel is important about both the Rust tutorial and manual. Please don't misunderstand me, no flame here, I am sending this message to help. I think good docs are extremely important to increase the size of a community, and in particular make more people contribute to Servo (the reason why I'm here).
If the Reference Manual for Rust tries to be complete and does not try to avoid language complexity, it can be from time to time hard to read because of one thing: examples are not well or often enough explained and are often too complex given the section they belong too. It's for instance difficult for the reader to understand an example of section n that uses notions explained only in section n+4. The Tutorial is the entry point for all people willing to investigate Rust and/or contribute to Servo. I think that document is super precious, super-important. Unfortunately, I don't think it is really a tutorial but only a lighter manual. Examples are here even more important than in the case of the Manual above. A good Tutorial is often built around one single programming task that becomes more and more complex as more features of the language are read and known. Furthermore, the Tutorial has clearly adopted the language complexity of the reference manual, something that I think should be in general avoided. I also think all examples should be buildable and produce a readable result on the console even if that result is a build or execution error. That would drastically help the reader. All in all, I think the Tutorial needs some love and probably a technical writer who is not working on the guts of Rust, someone who could vulgarize the notions of the Manual into an easy-to-read, simple-to-experiment, step-by-step tutorial and avoiding in general vocabulary inherited from programming language science. Best regards, </Daniel> _______________________________________________ Rust-dev mailing list [email protected] https://mail.mozilla.org/listinfo/rust-dev
