That was my point on another thread. I think it's best to have a top-bottom approach, ie, decribe everything else BUT the language first (how crates works, how to compile, how to test,...) and then introduce the memory concepts, etc.
I think the technical writer is a full time job, how to present things properly is not easy to do. He may have better way of introducing the language. I tend to agree with the assertion that its not a level of quality we can achieve with collaborating works, sadly. ----- Gaetan 2013/11/19 Thad Guidry <thadgui...@gmail.com> > >> I tend to agree with this, think that a collaborative approach is >> unlikely to produce a consistent and high quality tutorial. I don't want to >> discourage anybody but my current opinion is that we should hire an >> experienced technical writer to do this piece especially, with input from >> the wider community. Where I think collaboration is more likely to produce >> something nice is in a 'cookbook' style document, of which several people >> have already worked on seperately. Also of course API docs and the >> reference manual are places where individuals can plug in their own >> sections without impacting the overall narrative flow. >> >> > So I spent this evening going through the tutorial (.08). As an outsider > to Rust, I can tell you it does not fit any model of a tutorial, but > instead is an elongated language reference broken down into feature > sections. Which is highly useful in its design, and does say "This > tutorial assumes that the reader is already familiar with one or more > languages in the C family. Understanding of pointers and general memory > management techniques will help." BUT... > > It was not until section 17, that I finally met with a simple program that > could compile. That was 2 1/2 hours later before I was able to DO > SOMETHING. > > I would encourage the Mozilla team to hire a technical writer as Brian > suggests, that would turn the tutorial upside down... > > Start with something fun and entertaining in under 10 or 20 lines of Rust, > that would amuse and provide "hackability" to tweak and play with values, > mutability, and seeing the stack pop itself (half the developers in the > world, do not know or have to worry about "a stack"..but of course "should" > in any decent systems language :-) ), and then introduce garbage > collecting, etc. Introduce compile-able examples from the start, and > continue with working examples that actually produce errors and let the > user come to grips with the syntax & compiler error output, while coaching > them through fixing the errors, and learning the do's and don'ts of Rust's > current best practices. That would be a mighty fine tutorial and the > makings of a book for Rust itself. > > 2 cents and a haircut and I wish the team tremendous success on finding a > talented writer, > > -- > -Thad > +ThadGuidry <https://www.google.com/+ThadGuidry> > Thad on LinkedIn <http://www.linkedin.com/in/thadguidry/> > > _______________________________________________ > Rust-dev mailing list > Rust-dev@mozilla.org > https://mail.mozilla.org/listinfo/rust-dev > >
_______________________________________________ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
