edit documentation

* Add text explaining the basics of how the ansible provisioner works.
* Refactor the basic example to demonstrate the simplest case.
* Use active voice more consistently.

website/source/docs/provisioners/ansible.html.markdown

@@ -9,7 +9,10 @@ description: |-
 
 Type: `ansible`
 
-The `ansible` Packer provisioner allows Ansible playbooks to be run to provision the machine.
+The `ansible` Packer provisioner runs Ansible playbooks. It dynamically creates
+an Ansible inventory file configured to use SSH, runs an SSH server, executes
+`ansible-playbook`, and marshals Ansible plays through the SSH server to the
+machine being provisioned by Packer.
 
 ## Basic Example
 
@@ -21,10 +24,7 @@ DigitalOcean. Replace the mock `api_token` value with your own.
   "provisioners": [
     {
       "type": "ansible",
-      "playbook_file": "./playbook.yml",
+      "playbook_file": "./playbook.yml"
-      "extra_arguments": ["--private-key", "./id_packer-ansible", "-v", "-c", "paramiko"],
-      "ssh_authorized_key_file": "./id_packer-ansible.pub",
-      "ssh_host_key_file": "./packer_host_private_key"
     }
   ],
 
@@ -43,40 +43,39 @@ DigitalOcean. Replace the mock `api_token` value with your own.
 
 Required Parameters:
 
-- `playbook_file` - The playbook file to be run by Ansible.
+- `playbook_file` - The playbook to be run by Ansible.
 
 Optional Parameters:
 
 - `groups` (array of strings) - The groups into which the Ansible host
-	should be placed. When unspecified, the host is not associated with any
+  should be placed. When unspecified, the host is not associated with any
-	groups.
+  groups.
 
 - `host_alias` (string) - The alias by which the Ansible host should be known.
-	Defaults to `default`.
+  Defaults to `default`.
 
 - `ssh_host_key_file` (string) - The SSH key that will be used to run the SSH
   server on the host machine to forward commands to the target machine. Ansible
   connects to this server and will validate the identity of the server using
   the system known_hosts. The default behaviour is to generate and use a
-  onetime key, and disable host_key_verification in Ansible to allow it to
+  onetime key. Host key checking is disabled via the
-  connect to the server.
+  `ANSIBLE_HOST_KEY_CHECKING` environment variable if the key is generated.
 
 - `ssh_authorized_key_file` (string) - The SSH public key of the Ansible
   `ssh_user`. The default behaviour is to generate and use a onetime key. If
-  this file is generated, the corresponding private key will be passed via the
+  this key is generated, the corresponding private key is passed to
-  `--private-key` option to Ansible.
+  `ansible-playbook` with the `--private-key` option.
 
 - `local_port` (string) - The port on which to attempt to listen for SSH
   connections. This value is a starting point.  The provisioner will attempt
   listen for SSH connections on the first available of ten ports, starting at
-  `local_port`. When `local_port` is missing or empty, ansible-provisioner will
+  `local_port`. A system-chosen port is used when `local_port` is missing or
-  listen on a system-chosen port.
+  empty.
 
-
+- `sftp_command` (string) - The command to run on the machine being provisioned
-- `sftp_command` (string) - The command to run on the provisioned machine to
+  by Packer to handle the SFTP protocol that Ansible will use to transfer
-  handle the SFTP protocol that Ansible will use to transfer files. The command
+  files. The command should read and write on stdin and stdout, respectively.
-  should read and write on stdin and stdout, respectively. Defaults to
+  Defaults to `/usr/lib/sftp-server -e`.
-  `/usr/lib/sftp-server -e`.
 
 - `extra_arguments` (array of strings) - Extra arguments to pass to Ansible.