website: Clarify workspace concepts for remote backend

There are some differences between the Terraform CLI and Terraform Cloud ideas of workspaces.

This documentation aims to explain those differences and show different patterns for configuring the remote backend and the implications of different approaches.

website/docs/backends/types/remote.html.md

@@ -49,30 +49,49 @@ Currently the remote backend supports the following Terraform commands:
 
 ## Workspaces
 
-The remote backend can work with either a single remote workspace, or with
-multiple similarly-named remote workspaces (like `networking-dev` and
-`networking-prod`). The `workspaces` block of the backend configuration
+The remote backend can work with either a single remote Terraform Cloud workspace,
+or with multiple similarly-named remote workspaces (like `networking-dev`
+and `networking-prod`). The `workspaces` block of the backend configuration
 determines which mode it uses:
 
-- To use a single workspace, set `workspaces.name` to the remote workspace's
-  full name (like `networking`).
+- To use a single remote Terraform Cloud workspace, set `workspaces.name` to the
+  remote workspace's full name (like `networking`).
 
-- To use multiple workspaces, set `workspaces.prefix` to a prefix used in
+- To use multiple remote workspaces, set `workspaces.prefix` to a prefix used in
   all of the desired remote workspace names. For example, set
-  `prefix = "networking-"` to use a group of workspaces with names like
-  `networking-dev` and `networking-prod`.
+  `prefix = "networking-"` to use Terraform cloud workspaces with
+  names like `networking-dev` and `networking-prod`. This is helpful when
+  mapping multiple Terraform CLI [workspaces](../../state/workspaces.html)
+  used in a single Terraform configuration to multiple Terraform Cloud
+  workspaces.
 
-  When interacting with workspaces on the command line, Terraform uses
-  shortened names without the common prefix. For example, if
-  `prefix = "networking-"`, use `terraform workspace select prod` to switch to
-  the `networking-prod` workspace.
+When interacting with workspaces on the command line, Terraform uses
+shortened names without the common prefix. For example, if
+`prefix = "networking-"`, use `terraform workspace select prod` to switch to
+the Terraform CLI workspace `prod` within the current configuration. Remote
+Terraform operations such as `plan` and `apply` executed against that Terraform
+CLI workspace will be executed in the Terraform Cloud workspace `networking-prod`.
+
+Additionally, the [`${terraform.workspace}`](../../state/workspaces.html#current-workspace-interpolation)
+interpolation sequence should be removed from Terraform configurations that run
+remote operations against Terraform Cloud workspaces. The reason for this is that
+each Terraform Cloud workspace currently only uses the single `default` Terraform
+CLI workspace internally. In other words, if your Terraform configuration
+used `${terraform.workspace}` to return `dev` or `prod`, remote runs in Terraform Cloud
+would always evaluate it as `default` regardless of
+which workspace you had set with the `terraform workspace select` command. That
+would most likely not be what you wanted. (It is ok to use `${terraform.workspace}`
+in local operations.)
 
 The backend configuration requires either `name` or `prefix`. Omitting both or
 setting both results in a configuration error.
 
 If previous state is present when you run `terraform init` and the corresponding
 remote workspaces are empty or absent, Terraform will create workspaces and/or
-update the remote state accordingly.
+update the remote state accordingly. However, if your workspace needs variables
+set or requires a specific version of Terraform for remote operations, we
+recommend that you create your remote workspaces on Terraform Cloud before
+running any remote operations against them.
 
 ## Example Configuration
 
@@ -164,8 +183,12 @@ The following configuration options are supported:
   * `prefix` - (Optional) A prefix used in the names of one or more remote
     workspaces, all of which can be used with this configuration. The full
     workspace names are used in Terraform Cloud, and the short names
-    (minus the prefix) are used on the command line. If omitted, only the
-    default workspace can be used. This option conflicts with `name`.
+    (minus the prefix) are used on the command line for Terraform CLI workspaces.
+    If omitted, only the default workspace can be used. This option conflicts with `name`.
+    
+->  **Note** You must use the `name` key when configuring a `terraform_remote_state`
+data source that retrieves state from another Terraform Cloud workspace. The `prefix` key is only
+intended for use when configuring an instance of the remote backend.
 
 ## Excluding Files from Upload with .terraformignore
 

website/docs/state/workspaces.html.md

@@ -39,6 +39,13 @@ It was renamed in 0.10 based on feedback about confusion caused by the
 overloading of the word "environment" both within Terraform itself and within
 organizations that use Terraform.
 
+-> **Note**: The Terraform CLI workspace concept described in this document is
+different from but related to the Terraform Cloud
+[workspace](/docs/cloud/workspaces/index.html) concept.
+If you use multiple Terraform CLI workspaces in a single Terraform configuration
+and are migrating that configuration to Terraform Cloud, see this [migration
+document](/docs/cloud/migrate/workspaces.html).
+
 ## Using Workspaces
 
 Terraform starts with a single workspace named "default". This
@@ -70,7 +77,10 @@ Terraform workspace.
 
 Within your Terraform configuration, you may include the name of the current
 workspace using the `${terraform.workspace}` interpolation sequence. This can
-be used anywhere interpolations are allowed.
+be used anywhere interpolations are allowed. However, it should **not** be
+used in remote operations against Terraform Cloud workspaces. For an
+explanation, see the [remote backend](../backends/types/remote.html#workspaces)
+document.
 
 Referencing the current workspace is useful for changing behavior based
 on the workspace. For example, for non-default workspaces, it may be useful
@@ -195,4 +205,6 @@ meant to be a shared resource. They aren't a private, local-only notion
 
 The "current workspace" name is stored only locally in the ignored
 `.terraform` directory. This allows multiple team members to work on
-different workspaces concurrently.
+different workspaces concurrently. The "current workspace" name is **not**
+currently meaningful in Terraform Cloud workspaces since it will always
+have the value `default`.