Rollup merge of #39903 - binarycrusader:issue-39901, r=alexcrichton

[rust.git] / src / doc / index.md

diff --git a/src/doc/index.md b/src/doc/index.md
index 71dfcf0b067ec2395b45fb0652b36036d1dd6e7f..982e24ef69549621e6df4a5b917ecd6b482ce973 100644 (file)
--- a/src/doc/index.md
+++ b/src/doc/index.md
@@ -6,32 +6,42 @@ nav {
 }
 </style>
 
-This is an index of the documentation included with the Rust
-compiler. For more comprehensive documentation see [the
-website](https://www.rust-lang.org).
+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.
 
-[**The Rust Programming Language**][book]. Also known as "The Book",
-The Rust Programming Language is the most comprehensive resource for
-all topics related to Rust, and is the primary official document of
-the language.
+## API Documentation
 
-[**The Rust Reference**][ref]. While Rust does not have a
-specification, the reference tries to describe its working in
-detail. It is accurate, but not necessarily complete.
+Rust provides a standard library with a number of features; [we host its
+documentation here][api].
 
-[**Standard Library API Reference**][api]. Documentation for the
-standard library.
+## Extended Error Documentation
 
-[**The Rustonomicon**][nomicon]. An entire book dedicated to
-explaining how to write unsafe Rust code. It is for advanced Rust
-programmers.
+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.
 
-[**Compiler Error Index**][err]. Extended explanations of
-the errors produced by the Rust compiler.
+## The Rust Bookshelf
 
-[book]: book/index.html
-[ref]: reference.html
+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.
+* [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.
+
+Another few words about the reference: it is guaranteed to be accurate, but not
+complete. We now have a policy that all new features must be included in the
+reference before stabilization; however, we are still back-filling things that
+landed before then. That work is being tracked [here][38643].
+
+[Rust Learning]: https://github.com/ctjhoa/rust-learning
+[Docs.rs]: https://docs.rs/
 [api]: std/index.html
-[nomicon]: nomicon/index.html
+[ref]: reference/index.html
+[38643]: https://github.com/rust-lang/rust/issues/38643
 [err]: error-index.html
+[book]: book/index.html
+[nomicon]: nomicon/index.html