Clarify Homebrew/git install guidance

* Move Homebrew to the top, common case for new devs
* Note that `brew install rbenv` includes ruby-build by default
* Be clear that `rbenv init` instructions are needed for shell setup
* Be explicit about starting a new shell to pick up PATH/init changes
* Use rbenv-doctor to conclusively demonstrate correct setup
* Separate upgrade instructions for Homebrew vs Git installs

Related: https://github.com/rbenv/ruby-build/pull/1106

README.md

@@ -39,9 +39,10 @@ RVM?**](https://github.com/rbenv/rbenv/wiki/Why-rbenv%3F)
   * [Choosing the Ruby Version](#choosing-the-ruby-version)
   * [Locating the Ruby Installation](#locating-the-ruby-installation)
 * [Installation](#installation)
+  * [Homebrew on macOS](#homebrew-on-mac-os)
+    * [Upgrading with Homebrew](#upgrading-with-homebrew)
   * [Basic GitHub Checkout](#basic-github-checkout)
-    * [Upgrading](#upgrading)
+    * [Upgrading with Git](#upgrading-with-git)
-  * [Homebrew on Mac OS X](#homebrew-on-mac-os-x)
   * [How rbenv hooks into your shell](#how-rbenv-hooks-into-your-shell)
   * [Installing Ruby versions](#installing-ruby-versions)
     * [Installing Ruby gems](#installing-ruby-gems)
@@ -148,15 +149,63 @@ Version names to rbenv are simply the names of the directories in
   sure to fully uninstall RVM and remove any references to it from
   your shell initialization files before installing rbenv.
 
-If you're on Mac OS X, consider
+### Homebrew on macOS
-[installing with Homebrew](#homebrew-on-mac-os-x).
+
+If you're on macOS, we recommend installing rbenv with
+[Homebrew](https://brew.sh).
+
+1. Install rbenv.
+
+    ~~~ sh
+    $ brew install rbenv
+    ~~~
+
+   Note that this also installs `ruby-build`, so you'll be ready to
+   install other Ruby versions out of the box.
+
+2. Run `rbenv init` and follow the instructions to set up
+   rbenv integration with your shell. This is the step that will make
+   running `ruby` "see" the Ruby version that you choose with rbenv.
+
+3. Close your Terminal window and open a new one so your changes take
+   effect.
+
+4. Verify that rbenv is properly set up using this
+   [rbenv-doctor](https://github.com/rbenv/rbenv-installer/blob/master/bin/rbenv-doctor) script:
+
+    ~~~ sh
+    $ curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash
+    Checking for `rbenv' in PATH: /usr/local/bin/rbenv
+    Checking for rbenv shims in PATH: OK
+    Checking `rbenv install' support: /usr/local/bin/rbenv-install (ruby-build 20170523)
+    Counting installed Ruby versions: none
+      There aren't any Ruby versions installed under `~/.rbenv/versions'.
+      You can install Ruby versions like so: rbenv install 2.2.4
+    Checking RubyGems settings: OK
+    Auditing installed plugins: OK
+    ~~~
+
+5. That's it! Installing rbenv includes ruby-build, so now you're ready to
+   [install some other Ruby versions](#installing-ruby-versions) using
+   `rbenv install`.
+
+
+#### Upgrading with Homebrew
+
+To upgrade to the latest rbenv and update ruby-build with newly released
+Ruby versions, upgrade the Homebrew packages:
+
+~~~ sh
+$ brew upgrade rbenv ruby-build
+~~~
+
 
 ### Basic GitHub Checkout
 
-This will get you going with the latest version of rbenv and make it
+This will get you going with the latest version of rbenv without needing
-easy to fork and contribute any changes back upstream.
+a systemwide install.
 
-1. Check out rbenv into `~/.rbenv`.
+1. Clone rbenv into `~/.rbenv`.
 
     ~~~ sh
     $ git clone https://github.com/rbenv/rbenv.git ~/.rbenv
@@ -180,61 +229,42 @@ easy to fork and contribute any changes back upstream.
 
     **Zsh note**: Modify your `~/.zshrc` file instead of `~/.bash_profile`.
 
-3. Run `~/.rbenv/bin/rbenv init` for shell-specific instructions on how to
+3. Run `~/.rbenv/bin/rbenv init` and follow the instructions to set up
-   initialize rbenv to enable shims and autocompletion.
+   rbenv integration with your shell. This is the step that will make
+   running `ruby` "see" the Ruby version that you choose with rbenv.
 
 4. Restart your shell so that PATH changes take effect. (Opening a new
-   terminal tab will usually do it.) Now check if rbenv was set up:
+   terminal tab will usually do it.)
+
+5. Verify that rbenv is properly set up using this
+   [rbenv-doctor](https://github.com/rbenv/rbenv-installer/blob/master/bin/rbenv-doctor) script:
 
     ~~~ sh
-    $ type rbenv
+    $ curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash
-    #=> "rbenv is a function"
+    Checking for `rbenv' in PATH: /usr/local/bin/rbenv
+    Checking for rbenv shims in PATH: OK
+    Checking `rbenv install' support: /usr/local/bin/rbenv-install (ruby-build 20170523)
+    Counting installed Ruby versions: none
+      There aren't any Ruby versions installed under `~/.rbenv/versions'.
+      You can install Ruby versions like so: rbenv install 2.2.4
+    Checking RubyGems settings: OK
+    Auditing installed plugins: OK
     ~~~
 
-5. _(Optional)_ Install [ruby-build][], which provides the
+6. _(Optional)_ Install [ruby-build][], which provides the
    `rbenv install` command that simplifies the process of
    [installing new Ruby versions](#installing-ruby-versions).
 
-#### Upgrading
+#### Upgrading with Git
 
-If you've installed rbenv manually using git, you can upgrade your
+If you've installed rbenv manually using Git, you can upgrade to the
-installation to the cutting-edge version at any time.
+latest version by pulling from GitHub:
 
 ~~~ sh
 $ cd ~/.rbenv
 $ git pull
 ~~~
 
-To use a specific release of rbenv, check out the corresponding tag:
-
-~~~ sh
-$ cd ~/.rbenv
-$ git fetch
-$ git checkout v0.3.0
-~~~
-
-If you've [installed via Homebrew](#homebrew-on-mac-os-x), then upgrade
-via its `brew` command:
-
-~~~ sh
-$ brew update
-$ brew upgrade rbenv ruby-build
-~~~
-
-### Homebrew on Mac OS X
-
-As an alternative to installation via GitHub checkout, you can install
-rbenv and [ruby-build][] using the [Homebrew](http://brew.sh) package
-manager on Mac OS X:
-
-~~~
-$ brew update
-$ brew install rbenv
-$ rbenv init
-~~~
-
-You'll only ever have to run `rbenv init` once.
-
 ### How rbenv hooks into your shell
 
 Skip this section unless you must know what every line in your shell