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

Matthew McPherrin mozilla at mcpherrin.ca
Mon Apr 21 18:32:04 PDT 2014

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 <banderson at mozilla.com> 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
> Rust-dev at mozilla.org
> https://mail.mozilla.org/listinfo/rust-dev

More information about the Rust-dev mailing list