[rust-dev] Call for a "practical" Rust guide

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