From ab88f8ca0f80bb819ffa071ccd94403457fb73ff Mon Sep 17 00:00:00 2001
From: Nick Fagerlund <nick@hashicorp.com>
Date: Mon, 29 Oct 2018 11:00:24 -0700
Subject: [PATCH] website: Update and link the page about remote backend
 operations (#19203)

---
 website/docs/backends/operations.html.md | 33 +++++++++++++++++-------
 website/layouts/docs.erb                 |  4 +++
 2 files changed, 27 insertions(+), 10 deletions(-)

diff --git a/website/docs/backends/operations.html.md b/website/docs/backends/operations.html.md
index 948e7c965..690f1fe17 100644
--- a/website/docs/backends/operations.html.md
+++ b/website/docs/backends/operations.html.md
@@ -1,19 +1,32 @@
 ---
 layout: "docs"
-page_title: "Backends: Operations (refresh, plan, apply, etc.)"
-sidebar_current: "docs-backends-ops"
+page_title: "Backends: Remote Operations (plan, apply, etc.)"
+sidebar_current: "docs-backends-operations"
 description: |-
   Some backends support the ability to run operations (`refresh`, `plan`, `apply`, etc.) remotely. Terraform will continue to look and behave as if they're running locally while they in fact run on a remote machine.
 ---
 
-# Operations (plan, apply, etc.)
+# Remote Operations (plan, apply, etc.)
 
-Some backends support the ability to run operations (`refresh`, `plan`, `apply`,
-etc.) remotely. Terraform will continue to look and behave as if they're
-running locally while they in fact run on a remote machine.
+Most backends run all operations on the local system — although Terraform stores
+its state remotely with these backends, it still executes its logic locally and
+makes API requests directly from the system where it was invoked.
 
-Backends should not modify the actual infrastructure change behavior of
-these commands. They will only modify how they're invoked.
+This is simple to understand and work with, but when many people are
+collaborating on the same Terraform configurations, it requires everyone's
+execution environment to be similar. This includes sharing access to
+infrastructure provider credentials, keeping Terraform versions in sync,
+keeping Terraform variables in sync, and installing any extra software required
+by Terraform providers. This becomes more burdensome as teams get larger.
 
-At the time of writing, no backends support this. This shouldn't be linked
-in the sidebar yet!
+Some backends can run operations (`plan`, `apply`, etc.) on a remote machine,
+while appearing to execute locally. This enables a more consistent execution
+environment and more powerful access controls, without disrupting workflows
+for users who are already comfortable with running Terraform.
+
+Currently, [the `remote` backend](./types/remote.html) is the only backend to
+support remote operations, and [Terraform Enterprise](/docs/enterprise/index.html)
+is the only remote execution environment that supports it. For more information, see:
+
+- [The `remote` backend](./types/remote.html)
+- [Terraform Enterprise's CLI-driven run workflow](/docs/enterprise/run/cli.html)
diff --git a/website/layouts/docs.erb b/website/layouts/docs.erb
index 6452e293f..c9d6a757a 100644
--- a/website/layouts/docs.erb
+++ b/website/layouts/docs.erb
@@ -308,6 +308,10 @@
             <a href="/docs/backends/state.html">State Storage & Locking</a>
           </li>
 
+          <li<%= sidebar_current("docs-backends-operations") %>>
+            <a href="/docs/backends/operations.html">Remote Operations</a>
+          </li>
+
           <li<%= sidebar_current("docs-backends-types") %>>
             <a href="/docs/backends/types/index.html">Backend Types</a>
           </li>