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
