website/docs: document new provider lookup logic

website/docs/source/v2/providers/basic_usage.html.md

@@ -32,23 +32,22 @@ precise64 (vmware_fusion)
 
 ## Vagrant Up
 
-Once a provider is installed, it is used by calling `vagrant up` with the `--provider` flag,
-specifying the provider you want to back the machine. No other configuration
-is necessary! What this looks like:
+Once a provider is installed, you can use it by calling `vagrant up`
+with the `--provider` flag. This will force Vagrant to use that specific
+provider. No other configuration is necessary!
+
+In normal day-to-day usage, the `--provider` flag isn't necessary
+since Vagrant can usually pick the right provider for you. More details
+on how it does this is below.
 
 ```
 $ vagrant up --provider=vmware_fusion
 ```
 
-If the provider is well-behaved then everything should just work. Of course,
-each provider typically exposes custom configuration options to fine tune
-and control that provider, but defaults should work great to get started.
-
-From this point forward, you can use all the other commands without
-specifying a `--provider`; Vagrant is able to figure it out on its own.
-Specifically, once you run `vagrant up --provider`, Vagrant is able to see
-what provider is backing an existing machine, so commands such as `destroy`,
-`suspend`, etc. do not need to be told what provider to use.
+If you specified a `--provider` flag, you only need to do this for the
+`up` command. Once a machine is up and running, Vagrant is able to
+see what provider is backing a running machine, so commands such as
+`destroy`, `suspend`, etc. do not need to be told what provider to use.
 
 <div class="alert alert-info">
 	<h3>Limitations</h3>
@@ -65,3 +64,49 @@ what provider is backing an existing machine, so commands such as `destroy`,
 		Vagrant.
 	</p>
 </div>
+
+## Default Provider
+
+As mentioned earlier, you typically don't need to specify `--provider`
+_ever_. Vagrant is smart enough about being able to detect the provider
+you want for a given environment.
+
+Vagrant attempts to find the default provider in the following order:
+
+  1. The `--provider` flag on a `vagrant up` is chosen above all else, if
+     it is present.
+
+  2. If `VAGRANT_DEFAULT_PROVIDER` is set, it takes next priority and will
+     be the provider chosen.
+
+  3. Vagrant will go through all of the `config.vm.provider` calls in the
+     Vagrantfile and try each in order. It will choose the first provider
+     that is usable. For example, if you configure Hyper-V, it will never
+     be chosen on Mac this way. It must be both configured and usable.
+
+  4. Vagrant will go through all installed provider plugins (including the
+     ones that come with Vagrant), and find the first plugin that reports
+     it is usable. There is a priority system here: systems that are known
+     better have a higher priority than systems that are worse. For example,
+     if you have the VMware provider installed, it will always take priority
+     over VirtualBox.
+
+  5. If Vagrant still hasn't found any usable providers, it will error.
+
+Using this method, there are very few cases that Vagrant doesn't find the
+correct provider for you. This also allows each
+[Vagrantfile](/v2/vagrantfile/index.html) to define what providers
+the development environment is made for by ordering provider configurations.
+
+A trick is to use `config.vm.provider` with no configuration at the top of
+your Vagrantfile to define the order of providers you prefer to support:
+
+```ruby
+Vagrant.configure("2") do |config|
+  # ... other config up here
+
+  # Prefer VMware Fusion before VirtualBox
+  config.vm.provider "vmware_fusion"
+  config.vm.provider "virtualbox"
+end
+```