website: better document the dockerfile interaction with the builder

website/source/docs/builders/docker.html.markdown

@@ -10,7 +10,20 @@ The Docker builder builds [Docker](http://www.docker.io) images using
 Docker. The builder starts a Docker container, runs provisioners within
 this container, then exports the container for re-use.
 
-The Docker builder must run on a machine that supports Docker.
+Packer builds Docker containers _without_ the use of
+[Dockerfiles](http://docs.docker.io/en/latest/use/builder/).
+By not using Dockerfiles, Packer is able to provision
+containers with portable scripts or configuration management systems
+that are not tied to Docker in any way. It also has a simpler mental model:
+you provision containers much the same way you provision a normal virtualized
+or dedicated server. For more information, read the section on
+[Dockerfiles](#toc_3).
+
+The Docker builder must run on a machine that has Docker installed. Therefore
+the builder only works on machines that support Docker (modern Linux machines).
+If you want to use Packer to build Docker containers on another platform,
+use [Vagrant](http://www.vagrantup.com) to start a Linux environment, then
+run Packer within that environment.
 
 ## Basic Example
 
@@ -47,11 +60,32 @@ Optional:
 
 ## Dockerfiles
 
-This builder allows you to build Docker images _without_ Dockerfiles. If
-you have a Dockerfile already made, it is simple to just run `docker build`
-manually.
+This builder allows you to build Docker images _without_ Dockerfiles.
 
 With this builder, you can repeatably create Docker images without the use
 a Dockerfile. You don't need to know the syntax or semantics of Dockerfiles.
 Instead, you can just provide shell scripts, Chef recipes, Puppet manifests,
-etc. to provision your Docker container just like you would a regular machine.
+etc. to provision your Docker container just like you would a regular
+virtualized or dedicated machine.
+
+While Docker has many features, Packer views Docker simply as an LXC
+container runner. To that end, Packer is able to repeatably build these
+LXC containers using portable provisioning scripts.
+
+Dockerfiles have some additional features that Packer doesn't support
+which are able to be worked around. Many of these features will be automated
+by Packer in the future:
+
+* Dockerfiles will snapshot the container at each step, allowing you to
+  go back to any step in the history of building. Packer doesn't do this yet,
+  but inter-step snapshotting is on the way.
+
+* Dockerfiles can contain information such as exposed ports, shared
+  volumes, and other metadata. Packer builds a raw Docker container image
+  that has none of this metadata. You can pass in much of this metadata
+  at runtime with `docker run`.
+
+* Images made without dockerfiles are missing critical metadata that
+  make them easily pushable to the Docker registry. You can work around
+  this by using a metadata-only Dockerfile with the exported image and
+  building that. A future Packer version will automatically do this for you.