I think this sounds good overall. However, I don't think we can completely kill the tutorial: I think we still need a "Getting Started with Rust" document that is an expanded version of the tutorial section of the same name, and an abbreviated version of the rest of the tutorial. I imagine this is much more hand-holding than your practical guide.
That should probably go through Installing Rust, writing and running Hello World, and then some simple program involving at least using some standard library code, a struct, enum and function definition. Using a for loop and an if statement. Maybe a simple "guessing game" or something. I'd also imagine it being "localized" for each OS we support, especially with respect to installation, compiling, and running a program. In contrast, I'd expect the "practical guide" to include more information about what options are available for rustc installation, including the merits of source versus nightly installation, etc. Questions that a developer interested in seriously using rust may care about, but which would be "noise" for someone wanting to quickly try out Rust. On Mon, Apr 21, 2014 at 4:11 PM, Brian Anderson <[email protected]> wrote: > Hi. > > I've been convinced recently that Rust is missing crucial documentation of a > particular nature: using Rust in practice. I would like to have such a > standalone guide, and these are some ideas about what should be in it. > > This is a guide that runs through creating an entire Rust project from > installation, using the tools, writing code, through deployment, touching on > the practical aspects of coding Rust, not glossing over whatever ugly bits > are necessary to do real work. > > Some of the topics I might expect include: > > * Installation > * Running rustc > * lib.rs/bin.rs/mod.rs conventions > * Evolving a project from a single file to multi-file/mod/directory > * Picking the correct types for various problems > * Obtaining and using other crates > * Setting up a build system (not cargo to start, cargo when it's ready) > * Working with the compiler to find the correct algorithms. Show typical > ways you might concieve the solution incorrectly and how the compiler helps > guide you to the correct one. Particularly re: borrowck. > * Common Rust patterns (like?) > * Rust CI, other community resources? > * Using rust-bindgen to create bindings that don't already exist > * Error handling > * Practical corner cases and workarounds of various types, e.g. > - #[path], #[link_args]? > > There's some overlap here with the current tutorial, which I think is good, > since I want to find new homes for most of the content there. > > I've filed this as issue #13669, but have no plans to work on it personally > at this time. If anybody has an interest in taking it on, please coordinate > there. > > Finally, I'd like to update folks with a few words on how I'm currently > envisioning the Rust documentation story. > > I've become convinced that relatively small and self-contained guides are > our best format for producing standalone documentation about Rust. By being > small, they require minimal investment by any single individual, so we can > experiment quite freely with what docs are provided, what order they are > presented, and the schedule on which they are created. > > Right now I am aiming for three introductory guides, serving distinct > purposes: > > * "A 30-minute intro to Rust" - Very high-level, purely to excited > prospective users, let them know whether Rust is for them > * "The Philosophy of Rust" - Covers about a dozen subjects that are crucial > to understanding why Rust is like it is. It would be impossible to do > anything useful in Rust without understanding this material: stack vs. heap, > ownership, copying, moving, borrowing, lifetimes. Experienced devs will also > pick up a lot of basic syntax in passing. > * "Practical Rust" - Using Rust to build real software. > > After these, a new user should be well on their way to writing Rust, > especially after reading the various other guides on more focused topics. > > "The Philosophy of Rust" is a document that Sam Wright, Niko and I are > working on. The title will almost certainly change. Sam will have a new pull > request up soon. > > As to the existing tutorial, after the new docs mature I expect to demote it > to "The (old) Rust tutorial", then start looking for new homes for the > material there. This won't happen for a while, until the new docs are a good > enough substitute. > > Regards, > Brian > _______________________________________________ > 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
