Update the README.

README.md

@@ -1,63 +1,58 @@
 # "The" Vagrant
 
-Add a customizable vagrant environment into a project. This may be used in conjunction with the [drupal-skeleton](https://github.com/palantirnet/drupal-skeleton) and [the-build](https://github.com/palantirnet/the-build), or it may be used to retrofit an existing project with our current VM-based development environment.
+Add a customizable vagrant environment into a Drupal project. This may be used in conjunction with the [drupal-skeleton](https://github.com/palantirnet/drupal-skeleton) and [the-build](https://github.com/palantirnet/the-build), or it may be used to retrofit an existing project with a VM-based development environment.
 
 _Note: If you are setting up a new project, you likely want to start with [drupal-skeleton](https://github.com/palantirnet/drupal-skeleton)._
 
-## Dependencies
-
-This Vagrant configuration requires the following plugins:
+## Why the-vagrant?
 
-* [vagrant-hostmanager](https://github.com/devopsgroup-io/vagrant-hostmanager)
-* [vagrant-auto_network](https://github.com/oscar-stack/vagrant-auto_network)
+* Start from [a base box that comes with the basics installed](https://app.vagrantup.com/palantir/boxes/drupalbox) for fast, consistent startup
+* Use a thin layer of configuration to set up your project, without masking Vagrant itself
+* Customize with [Ansible playbooks](https://docs.ansible.com/ansible/latest/user_guide/playbooks.html) when necessary
+* Separate your local development environment from your build tools
 
-This setup will use a version of the [palantir/drupalbox](https://app.vagrantup.com/palantir/boxes/drupalbox) Vagrant box:
-
-| the-vagrant version | palantir/drupalbox version | Vagrant provider | Vagrant version |
-|---|---|---|---|
-| 2.2.0 | >= 1.2.0, < 2.0 | virtualbox | >= 2.1.0 |
-| 2.1.0 | >= 1.2.0, < 2.0 | virtualbox |
-| 2.0.1 | 1.1.1, 1.2.0 | virtualbox |
-| 2.0.0 | 1.1.0, 1.1.1 | virtualbox, vmware_desktop (drupalbox v1.1.0 only) |
-| 0.6.0 - 1.1.1 | >= 0.2.4, < 1.0 | virtualbox, vmware_desktop |
+## Dependencies
 
-\* Note that version 1.2.0 of the palantir/drupalbox VM requires updating to version 2.0.1 of palantirnet/the-vagrant.
+* [Vagrant](https://www.vagrantup.com/) >= 2.1.0
+* Vagrant plugins:
+ * [vagrant-hostmanager](https://github.com/devopsgroup-io/vagrant-hostmanager)
+ * [vagrant-auto_network](https://github.com/oscar-stack/vagrant-auto_network)
+* [Virtualbox](https://www.virtualbox.org/wiki/Downloads) >= 5.0
+* [Ansible](https://github.com/ansible/ansible)
 
 ## Installation
 
 To use the-vagrant on a project, you will need to:
 
-1. Require the `palantirnet/the-vagrant` package
-2. Run the-vagrant's install script to add and configure the Vagrantfile
-
-### Require the `palantirnet/the-vagrant` package with composer
-
-```sh
-$> composer require palantirnet/the-vagrant
-```
-
-### Runing the install script
-
-1. From within your project, run `vendor/bin/the-vagrant-installer`
-2. This will prompt you for project-specific configuration:
-  * The project hostname
-  * The project web root
-  * Enable Solr
-  * Enable HTTPS
-  * Make a project-specific copy of the Ansible roles and a copy of the default playbook
-  * OR make a project-specific Ansible playbook to be run _in addition_ to the default playbook
+1. Use composer to add the package to your project:
+
+    ```
+    composer require --dev palantirnet/the-vagrant
+    ```
+2. Run the-vagrant's install script to add and configure the Vagrantfile:
+
+    ```
+    vendor/bin/the-vagrant-installer
+    ```
+  * This will prompt you for project-specific configuration:
+    * The project hostname
+    * The project web root
+    * Enable Solr
+    * Enable HTTPS
+    * Make a project-specific copy of the Ansible roles and a copy of the default playbook
+    * OR make a project-specific Ansible playbook to be run _in addition_ to the default playbook
 3. Check in and commit the new Vagrantfile to git
 
-You can re-run the install script later if you need to change your configuration.
+If you need to change your configuration later, you can re-run the install script, or edit the `Vagrantfile` directly.
 
-## Upgrading
+## Updating
 
-To upgrade the-vagrant in a project, you will need to:
+To update an existing installation of `the-vagrant` in a project, you will need to:
 
 1. `composer update palantirnet/the-vagrant`
 2. Follow any steps from the [release notes](https://github.com/palantirnet/the-vagrant/releases).
 
-*Note:* If you need to update your VM, such as [drupalbox](https://app.vagrantup.com/palantir/boxes/drupalbox), you will need to run `vagrant destroy` then `vagrant box update` and `vagrant up`. Updating the VM doesn't always require updating The Vagrant.
+*Note:* If you need to update the underlying VM (the Vagrant box [drupalbox](https://app.vagrantup.com/palantir/boxes/drupalbox), which includes PHP, Apache, MySQL, and Solr), you will need to run `vagrant destroy` then `vagrant box update` and `vagrant up`. Updating the VM doesn't always require updating `the-vagrant`, and vice versa.
 
 ## Customizing your environment
 
@@ -151,9 +146,23 @@ By default, the-vagrant references ansible roles from the package at `vendor/pal
     }
   ```
 
-# Default Software
+## Default Software
+
+`the-vagrant` uses Vagrant boxes built with [palantirnet/devkit](https://github.com/palantirnet/devkit). Releases of this Vagrant base box [are on Vagrant Cloud](https://app.vagrantup.com/palantir/boxes/drupalbox). You can find more information about the specifics of accessing default software like MySQL, Solr, and Mailhog in the [Drupalbox README](https://github.com/palantirnet/devkit/blob/develop/drupalbox/README.md).
+
+### Compatibility between the-vagrant and base boxes
+Some versions of the-vagrant are coordinated with releases of the [palantir/drupalbox](https://app.vagrantup.com/palantir/boxes/drupalbox) Vagrant box:
+
+| the-vagrant version | palantir/drupalbox version | Vagrant provider | Vagrant version |
+|---|---|---|---|
+| 2.2.0 | >= 1.2.0, < 2.0 | virtualbox | >= 2.1.0 |
+| 2.1.0 | >= 1.2.0, < 2.0 | virtualbox |
+| 2.0.1 | 1.1.1, 1.2.0 | virtualbox |
+| 2.0.0 | 1.1.0, 1.1.1 | virtualbox, vmware_desktop (drupalbox v1.1.0 only) |
+| 0.6.0 - 1.1.1 | >= 0.2.4, < 1.0 | virtualbox, vmware_desktop |
+
+\* Note that version 1.2.0 of the palantir/drupalbox VM requires updating to version 2.0.1 of palantirnet/the-vagrant.
 
-`the-vagrant` uses Vagrant boxes built with [palantirnet/devkit](https://github.com/palantirnet/devkit). You can find more information about the specifics of accessing default software like MySQL, Solr, and Mailhog in the [Drupalbox README](https://github.com/palantirnet/devkit/blob/develop/drupalbox/README.md).
 
 ----
-Copyright 2016, 2017, 2018 Palantir.net, Inc.
+Copyright 2016 - 2020 Palantir.net, Inc.