I completely share your views, Daniel.
[Would have expressed them myself if I did not know (from experience) that
constructive critics by me (in english) usually are mistaken or misunderstood:
people just deny, argue, or reply violently. But you do a good job, here, in my
opinion.]
Denis
On 11/14/2013 04:03 PM, Daniel Glazman wrote:
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
_______________________________________________
Rust-dev mailing list
[email protected]
https://mail.mozilla.org/listinfo/rust-dev
