Updated provisioning getting started

1. Updated some formatting.
2. Tidied the example a little to make it less clunky.
3. Rewrote some text to make things clearer.

website/source/intro/getting-started/provision.html.md

@@ -3,20 +3,20 @@ layout: "intro"
 page_title: "Provision"
 sidebar_current: "gettingstarted-provision"
 description: |-
-  You're now able to create and modify infrastructure. This page introduces how to use provisioners to run basic shell scripts on instances when they're created.
+  Introduces provisioners that can initialize instances when they're created.
 ---
 
 # Provision
 
-You're now able to create and modify infrastructure. This page
+You're now able to create and modify infrastructure. Now let's see
-introduces how to use provisioners to run basic shell scripts on
+how to use provisioners to initialize instances when they're created.
-instances when they're created.
 
 If you're using an image-based infrastructure (perhaps with images
 created with [Packer](https://www.packer.io)), then what you've
 learned so far is good enough. But if you need to do some initial
-setup on your instances, provisioners let you upload files,
+setup on your instances, then provisioners let you upload files,
-run shell scripts, etc.
+run shell scripts, or install and trigger other software like
+configuration management tools, etc.
 
 ## Defining a Provisioner
 
@@ -29,25 +29,25 @@ resource "aws_instance" "example" {
   instance_type = "t2.micro"
 
   provisioner "local-exec" {
-    command = "echo ${aws_instance.example.public_ip} > file.txt"
+    command = "echo ${aws_instance.example.public_ip} > ip_address.txt"
   }
 }
 ```
 
-This adds a `provision` block within the `resource` block. Multiple
+This adds a `provisioner` block within the `resource` block. Multiple
-`provision` blocks can be added to define multiple provisioning steps.
+`provisioner` blocks can be added to define multiple provisioning steps.
 Terraform supports
 [multiple provisioners](/docs/provisioners/index.html),
-but for this example we use the "local-exec" provisioner.
+but for this example we are using the `local-exec` provisioner.
 
-The "local-exec" provisioner executes a command locally on the machine
+The `local-exec` provisioner executes a command locally on the machine
 running Terraform. We're using this provisioner versus the others so
 we don't have to worry about specifying any
 [connection info](/docs/provisioners/connection.html) right now.
 
 ## Running Provisioners
 
-Provisioners are run only when a resource is _created_. They
+Provisioners are only run when a resource is _created_. They
 are not a replacement for configuration management and changing
 the software of an already-running server, and are instead just
 meant as a way to bootstrap a server. For configuration management,
@@ -71,10 +71,10 @@ Apply complete! Resources: 2 added, 0 changed, 0 destroyed.
 
 Terraform will output anything from provisioners to the console,
 but in this case there is no output. However, we can verify
-everything worked by looking at the "file.txt" file:
+everything worked by looking at the `ip_address.txt` file:
 
 ```
-$ cat file.txt
+$ cat ip_address.txt
 54.192.26.128
 ```
 
@@ -82,21 +82,21 @@ It contains the IP, just as we asked!
 
 ## Failed Provisioners and Tainted Resources
 
-If a resource successfully creates but fails during provision,
+If a resource successfully creates but fails during provisioning,
 Terraform will error and mark the resource as "tainted." A
 resource that is tainted has been physically created, but can't
 be considered safe to use since provisioning failed.
 
-When you generate your next execution plan, Terraform will remove
+When you generate your next execution plan, Terraform not attempt to restart
-any tainted resources and create new resources, attempting to
+provisioning on the same resource because it isn't guaranteed to be safe. Instead,
-provision again. It does not attempt to restart provisioning on the
+Terraform will remove any tainted resources and create new resources, attempting to
-same resource because it isn't guaranteed to be safe.
+provision them again after creation.
 
-Terraform does not automatically roll back and destroy the resource
+Terraform also does not automatically roll back and destroy the resource
 during the apply when the failure happens, because that would go
 against the execution plan: the execution plan would've said a
 resource will be created, but does not say it will ever be deleted.
-But if you create an execution plan with a tainted resource, the
+If you create an execution plan with a tainted resource, however, the
 plan will clearly state that the resource will be destroyed because
 it is tainted.
 
@@ -106,7 +106,7 @@ Provisioning is important for being able to bootstrap instances.
 As another reminder, it is not a replacement for configuration
 management. It is meant to simply bootstrap machines. If you use
 configuration management, you should use the provisioning as a way
-to bootstrap the configuration management utility.
+to bootstrap the configuration management tool.
 
 In the next section, we start looking at [variables as a way to
 parameterize our configurations](/intro/getting-started/variables.html).