Improve documentation on r?

src/contributing.md

@@ -70,9 +70,11 @@ when contributing to Rust under [the git section](./git.md).
 [about-pull-requests]: https://help.github.com/articles/about-pull-requests/
 [development-models]: https://help.github.com/articles/about-collaborative-development-models/
 
+### r?
+
 All pull requests are reviewed by another person. We have a bot,
 [@rust-highfive][rust-highfive], that will automatically assign a random person
-to review your request.
+to review your request based on which files you changed.
 
 If you want to request that a specific person reviews your pull request, you
 can add an `r?` to the pull request description. For example,
@@ -84,6 +86,17 @@ make a documentation change, add
 to the end of the pull request description, and [@rust-highfive][rust-highfive] will assign
 [@steveklabnik][steveklabnik] instead of a random person. This is entirely optional.
 
+You can also assign a random reviewer from a specific team by writing `r? rust-lang/groupname`.
+So if you were making a diagnostics change, then you could get a reviewer from the diagnostics
+team by adding:
+
+    r? rust-lang/diagnostics
+
+For a full list of possible `groupname` check the `groups` section at the
+[rust highfive config file](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json).
+
+### CI
+
 In addition to being reviewed by a human, pull requests are automatically tested
 thanks to continuous integration (CI). Basically, every time you open and update
 a pull request, CI builds the compiler and tests it against the
@@ -100,6 +113,8 @@ computational resources each time you push a change. It is also perfectly fine
 productivity. In particular, we don't recommend running the full `./x.py test` suite locally,
 since it takes a very long time to execute.
 
+### r+
+
 After someone has reviewed your pull request, they will leave an annotation
 on the pull request with an `r+`. It will look something like this:
 

src/getting-started.md

@@ -387,7 +387,6 @@ incredibly helpful:
 [wd]: ./contributing.md#writing-documentation
 [wg]: https://rust-lang.github.io/compiler-team/working-groups/
 
-
 ## Contributor Procedures
 
 There are some official procedures to know about. This is a tour of the
@@ -396,11 +395,12 @@ highlights, but there are a lot more details, which we will link to below.
 ### Code Review
 
 When you open a PR on the `rust-lang/rust` repo, a bot called `@rust-highfive` will
-automatically assign a reviewer to the PR. The reviewer is the person that will
-approve the PR to be tested and merged. If you want a specific reviewer (e.g. a
-team member you've been working with), you can specifically request them by
-writing `r? @user` (e.g. `r? @eddyb`) in either the original post or a followup
-comment (you can see [this comment][r?] for example).
+automatically assign a reviewer to the PR based on which files you changed.
+The reviewer is the person that will approve the PR to be tested and merged.
+If you want a specific reviewer (e.g. a team member you've been working with),
+you can specifically request them by writing `r? @user` (e.g. `r? @eddyb`) in
+either the original post or a followup comment
+(you can see [this comment][r?] for example).
 
 Please note that the reviewers are humans, who for the most part work on `rustc`
 in their free time. This means that they can take some time to respond and review

src/walkthrough.md

@@ -184,7 +184,7 @@ When you open a PR on the [rust-lang/rust], a bot will assign your PR to a
 review. If there is a particular rust team member you are working with, you can
 request that reviewer by leaving a comment on the thread with `r?
 @reviewer-github-id` (e.g. `r? @eddyb`). If you don't know who to request,
-don't request anyone; the bot will assign someone automatically.
+don't request anyone; the bot will assign someone automatically based on which files you changed.
 
 The reviewer may request changes before they approve your PR. Feel free to ask
 questions or discuss things you don't understand or disagree with. However,