diff --git a/website/docs/import/usage.html.md b/website/docs/import/usage.html.md
index 9c71494a2..3d6aa8c4e 100644
--- a/website/docs/import/usage.html.md
+++ b/website/docs/import/usage.html.md
@@ -12,18 +12,23 @@ The `terraform import` command is used to import existing infrastructure.
The command currently can only import one resource at a time. This means
you can't yet point Terraform import to an entire collection of resources
-such as an AWS VPC and import all of it. A future version of Terraform will
-be able to do this.
+such as an AWS VPC and import all of it. This workflow will be improved in a
+future version of Terraform.
To import a resource, first write a resource block for it in your
-configuration, establishing the name by which it will be known in Terraform:
+configuration, establishing the name by which it will be known to Terraform:
```
-resource "aws_instance" "bar" {
+resource "aws_instance" "example" {
# ...instance configuration...
}
```
+The name "example" here is local to the module where it is declared and is
+chosen by the configuration author. This is distinct from any ID issued by
+the remote system, which may change over time while the resource name
+remains constant.
+
If desired, you can leave the body of the resource block blank for now and
return to fill it in once the instance is imported.
@@ -31,18 +36,22 @@ Now `terraform import` can be run to attach an existing instance to this
resource configuration:
```shell
-$ terraform import aws_instance.bar i-abcd1234
+$ terraform import aws_instance.example i-abcd1234
```
-The above command imports an AWS instance with the given ID and attaches
-it to the name `aws_instance.bar`. You can also import resources into modules.
-See the [resource addressing](/docs/internals/resource-addressing.html)
-page for more details on the full range of addresses supported.
+This command locates the AWS instance with ID `i-abcd1234` and attaches
+its existing settings, as described by the EC2 API, to the name
+`aws_instance.example` in the Terraform state.
-The ID given is dependent on the resource type being imported. For example,
-AWS instances use their direct IDs. However, AWS Route53 zones use the
-domain name itself. Console the resource documentation for details on what
-form of ID each resource expects.
+It is also possible to import to resources in child modules and to single
+instances of a resource with `count` set. See
+[_Resource Addressing_](/docs/internals/resource-addressing.html) for more
+details on how to specify a target resource.
+
+The syntax of the given ID is dependent on the resource type being imported.
+For example, AWS instances use an opaque ID issued by the EC2 API, but
+AWS Route53 Zones use the domain name itself. Consult the documentation for
+each importable resource for details on what form of ID is required.
As a result of the above command, the resource is recorded in the state file.
You can now run `terraform plan` to see how the configuration compares to
@@ -61,5 +70,5 @@ configuration, so it is necessary to consult the import output and create
a `resource` block in configuration for each secondary resource. If this is
not done, Terraform will plan to destroy the imported objects on the next run.
-If you want to rename or otherwise modify the imported resources, the
+If you want to rename or otherwise move the imported resources, the
[state management commands](/docs/commands/state/index.html) can be used.