Re-write the documentation index

src/doc/index.md

@@ -6,55 +6,72 @@ nav {
 }
 </style>
 
-This page is an overview of the documentation included with your Rust install.
-Other unofficial documentation may exist elsewhere; for example, the [Rust
-Learning] project collects documentation from the community, and [Docs.rs]
-builds documentation for individual Rust packages.
+Welcome to an overview of the documentation provided by the Rust project.
+All of these projects are managed by the Docs Team; there are other
+unofficial documentation resources as well!
 
-# API Documentation
+Many of these resources take the form of "books"; we collectively call these
+"The Rust Bookshelf." Some are large, some are small.
 
-Rust provides a standard library with a number of features; [we host its
-documentation here][api].
+## Learn Rust
 
-# Extended Error Documentation
+If you'd like to learn Rust, this is the spot for you! All of these resources
+assume that you have programmed before, but not in any specific language:
+
+### The Rust Programming Language
+
+Affectionately nicknamed "the book," [The Rust Programming
+Language](book/index.html) will give you an overview of the language from
+first principles. You'll build a few projects along the way, and by the end,
+you'll have a solid grasp of the language.
+
+### Rust By Example
+
+If reading multiple hundreds of pages about a language isn't your style, then
+[Rust By Example](rust-by-example/index.html) has you covered. While the book talks about code with
+a lot of words, RBE shows off a bunch of code, and keeps the talking to a
+minimum. It also includes exercises!
+
+## Use Rust
+
+Once you've gotten familliar with the language, these resources can help you
+when you're actually using it day-to-day.
+
+### The Standard Library
+
+Rust's standard library has [extensive API documentation](std/index.html),
+with explanations of how to use various things, as well as example code for
+accomplishing various tasks.
+
+### The Cargo Book
+
+[The Cargo Book](cargo/index.html) is a guide to Cargo, Rust's build tool and dependency manager.
+
+### The Rustdoc Book
+
+[The Rustdoc Book](rustdoc/index.html) describes our documentation tool, `rustdoc`.
+
+### Extended Error Listing
 
 Many of Rust's errors come with error codes, and you can request extended
-diagnostics from the compiler on those errors. We also [have the text of those
-extended errors on the web][err], if you prefer to read them that way.
-
-# The Rust Bookshelf
-
-Rust provides a number of book-length sets of documentation, collectively
-nicknamed 'The Rust Bookshelf.'
-
-* [The Rust Programming Language][book] teaches you how to program in Rust.
-* [Rust By Example][rbe] teaches you how to program in Rust using editable examples.
-* [The Cargo Book][cargo-book] is a guide to Cargo, Rust's build tool and dependency manager.
-* [The Unstable Book][unstable-book] has documentation for unstable features.
-* [The Rustonomicon][nomicon] is your guidebook to the dark arts of unsafe Rust.
-* [The Reference][ref] is not a formal spec, but is more detailed and comprehensive than the book.
-* [The Rustdoc Book][rustdoc-book] describes our documentation tool, `rustdoc`.
-
-Initially, documentation lands in the Unstable Book, and then, as part of the
-stabilization process, is moved into the Book, Nomicon, or Reference.
-
-Another few words about the reference: it is guaranteed to be accurate, but not
-complete. We have a policy that features must have documentation to be stabilized,
-but we did not always have this policy, and so there are some stable things that
-are not yet in the reference. We're working on back-filling things that landed
-before this policy was put into place. That work is being tracked
-[here][refchecklist].
-
-[Rust Learning]: https:/ctjhoa/rust-learning
-[Docs.rs]: https://docs.rs/
-[api]: std/index.html
-[ref]: reference/index.html
-[refchecklist]: https:/rust-lang-nursery/reference/issues/9
-[err]: error-index.html
-[book]: book/index.html
-[rbe]: rust-by-example/index.html
-[nomicon]: nomicon/index.html
-[unstable-book]: unstable-book/index.html
-[rustdoc-book]: rustdoc/index.html
-[cargo-book]: cargo/index.html
+diagnostics from the compiler on those errors. You can also [read them
+here](error-index.html), if you prefer to read them that way.
+
+## Master Rust
+
+Once you're quite familiar with the language, you may find these advanced
+resources useful.
+
+### The Reference
+
+[The Reference](reference/index.html) is not a formal spec, but is more detailed and
+comprehensive than the book.
+
+### The Rustonomicon
+
+[The Rustonomicon](nomicon/index.html) is your guidebook to the dark arts of unsafe
+Rust. It's also sometimes called "the 'nomicon."
+
+### The Unstable Book
 
+[The Unstable Book](unstable-book/index.html) has documentation for unstable features.