Auto merge of #28269 - petrochenkov:docorder, r=steveklabnik

This is what I was talking about in https://github.com/rust-lang/rust/pull/26462#issuecomment-113883744

r? @steveklabnik 

1 files changed, 19 insertions, 17 deletions

diff --git a/src/doc/index.md b/src/doc/index.md
index 8ca50667507..1e667d3600f 100644
--- a/src/doc/index.md
+++ b/src/doc/index.md
@@ -20,13 +20,30 @@ series of small examples.
 
 [rbe]: http://rustbyexample.com/
 
-# The Standard Library
+# Language Reference
+
+Rust does not have an exact specification yet, but an effort to describe as much of
+the language in as much detail as possible is in [the reference](reference.html).
+
+# Standard Library Reference
 
 We have [API documentation for the entire standard
 library](std/index.html). There's a list of crates on the left with more
 specific sections, or you can use the search bar at the top to search for
 something if you know its name.
 
+# Tools
+
+[Cargo](https://crates.io) is the Rust's package manager providing access to libraries
+beyond the standard one, and its website contains lots of good documentation.
+
+[`rustdoc`](book/documentation.html) is the Rust's documentation generator, a tool converting
+annotated source code into HTML docs.
+
+A bunch of non-official tools are available, such as [Racer](https://github.com/phildawes/racer)
+(code completion engine), or [rustfmt](https://github.com/nrc/rustfmt) (source code formatter),
+or text editor plugins.
+
 # Community & Getting Help
 
 If you need help with something, or just want to talk about Rust with others,
@@ -54,25 +71,10 @@ There is an active [subreddit](https://reddit.com/r/rust) with lots of
 discussion and news about Rust.
 
 There is also a [user forum](https://users.rust-lang.org), for all
-user-oriented discussion, and a [developer 
+user-oriented discussion, and a [developer
 forum](https://internals.rust-lang.org/), where the development of Rust
 itself is discussed.
 
-# Specification
-
-Rust does not have an exact specification, but an effort to describe as much of
-the language in as much detail as possible is in [the reference](reference.html).
-
-# Tools
-
-Rust is still a young language, so there isn't a ton of tooling yet, but the
-tools we have are really nice.
-
-[Cargo](https://crates.io) is Rust's package manager, and its website contains
-lots of good documentation.
-
-[`rustdoc`](book/documentation.html) is used to generate documentation for Rust code.
-
 # FAQs
 
 There are questions that are asked quite often, so we've made FAQs for them: