From a51fc610143b46c5bf952f29b14e795c139cacac Mon Sep 17 00:00:00 2001
From: Nick Fagerlund <nick@hashicorp.com>
Date: Mon, 9 Jul 2018 15:28:30 -0700
Subject: [PATCH] website: Revise "atlas" backend page

Add links to important docs (like user tokens), and explain that this isn't part
of our recommended primary workflows anymore.
---
 .../types/terraform-enterprise.html.md        | 40 ++++++++++++-------
 1 file changed, 25 insertions(+), 15 deletions(-)

diff --git a/website/docs/backends/types/terraform-enterprise.html.md b/website/docs/backends/types/terraform-enterprise.html.md
index c9bc8801c..d8493955d 100644
--- a/website/docs/backends/types/terraform-enterprise.html.md
+++ b/website/docs/backends/types/terraform-enterprise.html.md
@@ -10,29 +10,35 @@ description: |-
 
 **Kind: Standard (with no locking)**
 
-Stores the state in [Terraform Enterprise](https://www.terraform.io/docs/providers/index.html).
+Reads and writes state from a [Terraform Enterprise](/docs/enterprise/index.html)
+workspace.
 
-You can create a new workspace in the
-Workspaces section and generate new token in the Tokens page under Settings.
+-> **Why is this called "atlas"?** Before it was a standalone offering,
+Terraform Enterprise was part of an integrated suite of enterprise products
+called Atlas. This backend predates the current version Terraform Enterprise, so
+it uses the old name.
 
-~> **Why is this called "atlas"?** Atlas was previously a commercial offering
-from HashiCorp that included a full suite of enterprise products. The products
-have since been broken apart into their individual products, like **Terraform
-Enterprise**. While this transition is in progress, you may see references to
-"atlas" in the documentation. We apologize for the inconvenience.
+This backend is useful for uncommon tasks like migrating state into a Terraform
+Enterprise workspace, but we no longer recommend using it as part of your
+day-to-day Terraform workflow. Since it performs runs outside of Terraform
+Enterprise and updates state directly, it does not support Terraform
+Enterprise's collaborative features like [workspace
+locking](/docs/enterprise/run/index.html). To perform Terraform Enterprise runs
+from the command line, use [Terraform Enterprise's CLI-driven
+workflow](/docs/enterprise/run/cli.html) instead.
 
 ## Example Configuration
 
 ```hcl
 terraform {
   backend "atlas" {
-    name         = "bigbang/example"
+    name = "example_corp/networking-prod"
   }
 }
 ```
 
-Note that for the access token we recommend using a
-[partial configuration](/docs/backends/config.html).
+We recommend using a [partial configuration](/docs/backends/config.html) and
+omitting the access token, which can be provided as an environment variable.
 
 ## Example Referencing
 
@@ -40,7 +46,7 @@ Note that for the access token we recommend using a
 data "terraform_remote_state" "foo" {
   backend = "atlas"
   config {
-    name         = "bigbang/example"
+    name = "example_corp/networking-prod"
   }
 }
 ```
@@ -49,6 +55,10 @@ data "terraform_remote_state" "foo" {
 
 The following configuration options / environment variables are supported:
 
- * `name` - (Required) Full name of the environment (`<username>/<name>`)
- * `ATLAS_TOKEN`/ `access_token`  - (Required) Terraform Enterprise API token. It is recommended that `ATLAS_TOKEN` is set as an environment variable rather than using `access_token` in the configuration.
- * `address` - (Optional) Address to alternative Terraform Enterprise location (Terraform Enterprise endpoint)
+* `name` - (Required) Full name of the workspace (`<ORGANIZATION>/<WORKSPACE>`).
+* `ATLAS_TOKEN`/ `access_token`  - (Required) A Terraform Enterprise [user API
+  token](/docs/enterprise/users-teams-organizations/users.html#api-tokens). We
+  recommend using the `ATLAS_TOKEN` environment variable rather than setting
+  `access_token` in the configuration.
+* `address` - (Optional) The hostname of a Terraform Enterprise instance.
+  (Defaults to the SaaS version of Terraform Enterprise.)