website: docs for parallelism setting

/cc @stack72 @knuckolls @mitchellh

command/apply.go

@@ -326,6 +326,9 @@ Options:
 
   -no-color              If specified, output won't contain any color.
 
+  -parallelism=n         Limit the number of concurrent operations.
+                         Defaults to 10.
+
   -refresh=true          Update state prior to checking for differences. This
                          has no effect if a plan file is given to apply.
 

command/plan.go

@@ -186,7 +186,7 @@ Options:
   -out=path           Write a plan file to the given path. This can be used as
                       input to the "apply" command.
 
-  -parallelism=#      Limit the number of concurrent operations. Defaults to 10.
+  -parallelism=n      Limit the number of concurrent operations. Defaults to 10.
 
   -refresh=true       Update state prior to checking for differences.
 

website/source/docs/commands/apply.html.markdown

@@ -35,6 +35,9 @@ The command-line flags are all optional. The list of available flags are:
 
 * `-no-color` - Disables output with coloring.
 
+* `-parallelism=n` - Limit the number of concurrent operation as Terraform
+  [walks the graph](/docs/internals/graph.html#walking-the-graph).
+
 * `-refresh=true` - Update the state for each resource prior to planning
   and applying. This has no effect if a plan file is given directly to
   apply.

website/source/docs/commands/plan.html.markdown

@@ -48,6 +48,9 @@ The command-line flags are all optional. The list of available flags are:
   changes shown in this plan are applied. Read the warning on saved
   plans below.
 
+* `-parallelism=n` - Limit the number of concurrent operation as Terraform
+  [walks the graph](/docs/internals/graph.html#walking-the-graph).
+
 * `-refresh=true` - Update the state prior to checking for differences.
 
 * `-state=path` - Path to the state file. Defaults to "terraform.tfstate".

website/source/docs/internals/graph.html.md

@@ -92,7 +92,24 @@ Building the graph is done in a series of sequential steps:
   1. Validate the graph has no cycles and has a single root.
 
 ## Walking the Graph
+<a id="walking-the-graph"></a>
 
 To walk the graph, a standard depth-first traversal is done. Graph
-walking is done with as much parallelism as possible: a node is walked
-as soon as all of its dependencies are walked.
+walking is done in parallel: a node is walked as soon as all of its
+dependencies are walked.
+
+The amount of parallelism is limited using a semaphore to prevent too many
+concurrent operations from overwhelming the resources of the machine running
+Terraform. By default, up to 10 nodes in the graph will be processed
+concurrently. This number can be set using the `-parallelism` flag on the
+[plan](/docs/commands/plan.html), [apply](/docs/commands/apply.html), and
+[destroy](/docs/commands/destroy.html) commands.
+
+Setting `-parallelism` is considered an advanced operation and should not be
+necessary for normal usage of Terraform. It may be helpful in certain special
+use cases or to help debug Terraform issues.
+
+Note that some providers (AWS, for example), handle API rate limiting issues at
+a lower level by implementing graceful backoff/retry in their respective API
+clients. For this reason, Terraform does not use this `parallelism` feature to
+address API rate limits directly.