Merge pull request #8421 from mitchellh/b-vs

website: update vs

website/source/intro/vs/cli-tools.md

@@ -13,7 +13,26 @@ description: |-
 # Vagrant vs. CLI Tools
 
 Virtualization software like VirtualBox and VMware come with command line
-utilities for managing the lifecycle of machines on their platform. Vagrant
-actually uses many of these utilities internally. The difference between these
-CLI tools and Vagrant is that Vagrant provides a declarative, reproducible,
-idempotent workflow.
+utilities for managing the lifecycle of machines on their platform. Many
+people make use of these utilities to write their own automation. Vagrant
+actually uses many of these utilities internally.
+
+The difference between these CLI tools and Vagrant is that Vagrant builds
+on top of these utilities in a number of ways while still providing a
+consistent workflow. Vagrant supports multiple synced folder types, multiple
+provisioners to setup the machine, automatic SSH setup, creating HTTP tunnels
+into your development environment, and more. All of these can be configured
+using a single simple configuration file.
+
+Vagrant still has a number of improvements over manual scripting even if you
+ignore all the higher-level features Vagrant provides. The command-line
+utilities provided by virtualization software often change each version
+or have subtle bugs with workarounds. Vagrant automatically detects the
+version, uses the correct flags, and can work around known issues. So if
+you're using one version of VirtualBox and a co-worker is using a different
+version, Vagrant will still work consistently.
+
+For highly-specific workflows that don't change often, it can still be
+beneficial to maintain custom scripts. Vagrant is targeted at building
+development environments but some advanced users still use the CLI tools
+underneath to do other manual things.

website/source/intro/vs/docker.html.md

@@ -9,14 +9,26 @@ description: |-
 
 # Vagrant vs. Docker
 
-Vagrant uses kernel-level isolation whereas Docker uses userland-level
-isolation. In practice, this means Vagrant will provide more isolation from your
-virtual machines than Docker, but Docker will be faster to boot machines. After
-booting, speeds are roughly equivalent.
+Vagrant is a tool focused on providing a consistent development environment
+workflow across multiple operation systems. Docker is a container management
+that can consistently run software as long as a containerization system exists.
 
-Docker also lacks support for certain operating systems (like Windows and BSD).
-If your target deployment is a Windows environment, Docker will not provide the
-same production parity as a tool like Vagrant.
+Containers are generally more lightweight than virtual machines, so starting
+and stopping containers is extremely fast. Most common development machines
+don't have a containerization system built-in, and Docker uses a virtual machine
+with Linux installed to provide that.
 
-Both Vagrant and Docker have a vast library of community-contributed "images" or
-"boxes" to choose from.
+Currently, Docker lacks support for certain operating systems (such as
+Windows and BSD). If your target deployment is one of these operating systems,
+Docker will not provide the same production parity as a tool like Vagrant.
+Vagrant will allow you to run a Windows development environment on Mac or Linux,
+as well.
+
+For microservice heavy environments, Docker can be attractive because you
+can easily start a single Docker VM and start many containers above that
+very quickly. This is a good use case for Docker. Vagrant can do this as well
+with the Docker provider. A primary benefit for Vagrant is a consistent workflow
+but there are many cases where a pure-Docker workflow does make sense.
+
+Both Vagrant and Docker have a vast library of community-contributed "images"
+or "boxes" to choose from.

website/source/intro/vs/terraform.html.md

@@ -9,15 +9,29 @@ description: |-
 
 # Vagrant vs. Terraform
 
-Vagrant is a tool for managing virtual machines. [Terraform][terraform] is
-another open source tool from [HashiCorp][hashicorp] which enables
-infrastructure as code.
+Vagrant and [Terraform][terraform] are both projects from [HashiCorp][hashicorp].
+Vagrant is a tool focused for managing development environments and
+Terraform is a tool for building infrastructure.
 
-Both Vagrant and Terraform use a declarative syntax to express the desired,
-final state of a system. Vagrant's focus is on development environments whereas
-Terraform's focus is on remote APIs and cloud resources. While Terraform has
-provisioners, they are not as full-featured as those in Vagrant. Vagrant cannot
-manage cloud resources without third-party plugins.
+Terraform can decribe complex sets of infrastructure that exists
+locally or remotely. It is focused on building and changing that infrastructure
+over time. The minimal aspects of virtual machine lifecycle can be reproduced
+in Terraform, sometimes leading to confusion with Vagrant.
+
+Vagrant provides a number of higher level features that Terraform doesn't.
+Synced folders, automatic networking, HTTP tunneling, and more are features
+provided by Vagrant to ease development environment usage. Because Terraform
+is focused on infrastructure management and not development environments,
+these features are out of scope for that project.
+
+The primary usage of Terraform is for managing remote resources in cloud
+providers such as AWS. Terraform is designed to be able to manage extremely
+large infrastructures that span multiple cloud providers. Vagrant is designed
+primarily for local development environments that use only a handful of
+virtual machines at most.
+
+Vagrant is for development environments. Terraform is for more general
+infrastructure management.
 
 [hashicorp]: https://www.hashicorp.com
 [terraform]: https://www.terraform.io