From fc4ceedc6d2b5d2a93511e5dadd442c984044745 Mon Sep 17 00:00:00 2001
From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com>
Date: Wed, 5 Jan 2022 11:08:33 -0500
Subject: [PATCH 01/11] Remove overview page and update notes on provisioner
 pages

---
 .../language/resources/provisioners/chef.mdx  |  3 ++-
 .../resources/provisioners/connection.mdx     | 27 ++++++++++---------
 .../language/resources/provisioners/file.mdx  |  4 +--
 .../resources/provisioners/habitat.mdx        |  3 ++-
 .../language/resources/provisioners/index.mdx | 12 ---------
 .../resources/provisioners/local-exec.mdx     |  4 +--
 .../resources/provisioners/null_resource.mdx  |  4 +++
 .../resources/provisioners/puppet.mdx         |  3 ++-
 .../resources/provisioners/remote-exec.mdx    |  6 ++---
 .../provisioners/salt-masterless.mdx          |  3 ++-
 10 files changed, 34 insertions(+), 35 deletions(-)
 delete mode 100644 website/docs/language/resources/provisioners/index.mdx

diff --git a/website/docs/language/resources/provisioners/chef.mdx b/website/docs/language/resources/provisioners/chef.mdx
index 9ec4887e2..99419c11e 100644
--- a/website/docs/language/resources/provisioners/chef.mdx
+++ b/website/docs/language/resources/provisioners/chef.mdx
@@ -11,7 +11,8 @@ The `chef` provisioner installs, configures and runs the Chef Client on a remote
 resource. The `chef` provisioner supports both `ssh` and `winrm` type
 [connections](/language/resources/provisioners/connection).
 
-!> **Note:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. For more information, see [the main Provisioners page](/language/resources/provisioners).
+!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. Refer to
+[Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Requirements
 
diff --git a/website/docs/language/resources/provisioners/connection.mdx b/website/docs/language/resources/provisioners/connection.mdx
index eb1ccff5f..22a4c16a0 100644
--- a/website/docs/language/resources/provisioners/connection.mdx
+++ b/website/docs/language/resources/provisioners/connection.mdx
@@ -11,19 +11,10 @@ Most provisioners require access to the remote resource via SSH or WinRM, and
 expect a nested `connection` block with details about how to connect.
 
 -> **Note:** Provisioners should only be used as a last resort. For most
-common situations there are better alternatives. For more information, see
-[the main Provisioners page](/language/resources/provisioners).
+common situations there are better alternatives. Refer to
+[Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
--> **Note:** In Terraform 0.11 and earlier, providers could set default values
-for some connection settings, so that `connection` blocks could sometimes be
-omitted. This feature was removed in 0.12 in order to make Terraform's behavior
-more predictable.
-
--> **Note:** Since the SSH connection type is most often used with
-newly-created remote resources, validation of SSH host keys is disabled by
-default. In scenarios where this is not acceptable, a separate mechanism for
-key distribution could be established and the `host_key` directive documented
-below explicitly set to verify against a specific key or signing CA.
+## Connection Block
 
 Connection blocks don't take a block label, and can be nested within either a
 `resource` or a `provisioner`.
@@ -37,6 +28,18 @@ One use case for providing multiple connections is to have an initial
 provisioner connect as the `root` user to set up user accounts, and have
 subsequent provisioners connect as a user with more limited permissions.
 
+Since the SSH connection type is most often used with
+newly-created remote resources, validation of SSH host keys is disabled by
+default. In scenarios where this is not acceptable, a separate mechanism for
+key distribution could be established and the `host_key` directive documented
+below explicitly set to verify against a specific key or signing CA.
+
+-> **Note:** In Terraform 0.11 and earlier, providers could set default values
+for some connection settings, so that `connection` blocks could sometimes be
+omitted. This feature was removed in 0.12 in order to make Terraform's behavior
+more predictable.
+
+
 ## Example usage
 
 ```hcl
diff --git a/website/docs/language/resources/provisioners/file.mdx b/website/docs/language/resources/provisioners/file.mdx
index 83dfb7a90..255814cd7 100644
--- a/website/docs/language/resources/provisioners/file.mdx
+++ b/website/docs/language/resources/provisioners/file.mdx
@@ -13,8 +13,8 @@ executing Terraform to the newly created resource. The `file` provisioner
 supports both `ssh` and `winrm` type [connections](/language/resources/provisioners/connection).
 
 -> **Note:** Provisioners should only be used as a last resort. For most
-common situations there are better alternatives. For more information, see
-[the main Provisioners page](/language/resources/provisioners).
+common situations there are better alternatives. Refer to
+[Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Example usage
 
diff --git a/website/docs/language/resources/provisioners/habitat.mdx b/website/docs/language/resources/provisioners/habitat.mdx
index c8ab535d1..cdd8f8bf9 100644
--- a/website/docs/language/resources/provisioners/habitat.mdx
+++ b/website/docs/language/resources/provisioners/habitat.mdx
@@ -9,7 +9,8 @@ description: >-
 
 The `habitat` provisioner installs the [Habitat](https://habitat.sh) supervisor and loads configured services. This provisioner only supports Linux targets using the `ssh` connection type at this time.
 
-!> **Note:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. For more information, see [the main Provisioners page](/language/resources/provisioners).
+!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. Refer to
+[Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Requirements
 
diff --git a/website/docs/language/resources/provisioners/index.mdx b/website/docs/language/resources/provisioners/index.mdx
deleted file mode 100644
index badd56b09..000000000
--- a/website/docs/language/resources/provisioners/index.mdx
+++ /dev/null
@@ -1,12 +0,0 @@
----
-page_title: Provisioners Overview - Configuration Language
-description: >-
-  Provisioners model specific actions on a local or remote machine to prepare
-  servers or other infrastructure for service.
----
-
-# Provisioners
-
-Provisioners can be used to model specific actions on the local machine or on a
-remote machine in order to prepare servers or other infrastructure objects for
-service.
diff --git a/website/docs/language/resources/provisioners/local-exec.mdx b/website/docs/language/resources/provisioners/local-exec.mdx
index 02eec0ef7..8298cfbe7 100644
--- a/website/docs/language/resources/provisioners/local-exec.mdx
+++ b/website/docs/language/resources/provisioners/local-exec.mdx
@@ -19,8 +19,8 @@ run, there is no guarantee that it will be in an operable state - for example
 system services such as `sshd` may not be started yet on compute resources.
 
 -> **Note:** Provisioners should only be used as a last resort. For most
-common situations there are better alternatives. For more information, see
-[the main Provisioners page](/language/resources/provisioners).
+common situations there are better alternatives. Refer to
+[Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Example usage
 
diff --git a/website/docs/language/resources/provisioners/null_resource.mdx b/website/docs/language/resources/provisioners/null_resource.mdx
index 3e7b3fd65..0ba1294a9 100644
--- a/website/docs/language/resources/provisioners/null_resource.mdx
+++ b/website/docs/language/resources/provisioners/null_resource.mdx
@@ -19,6 +19,10 @@ details](/language/resources/provisioners/connection) on a `null_resource`. You
 use its `triggers` argument and any meta-arguments to control exactly where in
 the dependency graph its provisioners will run.
 
+-> **Note:** Provisioners should only be used as a last resort. For most
+common situations there are better alternatives. Refer to
+[Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
+
 ## Example usage
 
 ```hcl
diff --git a/website/docs/language/resources/provisioners/puppet.mdx b/website/docs/language/resources/provisioners/puppet.mdx
index e0894c271..5563a369e 100644
--- a/website/docs/language/resources/provisioners/puppet.mdx
+++ b/website/docs/language/resources/provisioners/puppet.mdx
@@ -11,7 +11,8 @@ The `puppet` provisioner installs, configures and runs the Puppet agent on a
 remote resource. The `puppet` provisioner supports both `ssh` and `winrm` type
 [connections](/language/resources/provisioners/connection).
 
-!> **Note:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. For more information, see [the main Provisioners page](/language/resources/provisioners).
+!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. Refer to
+[Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Requirements
 
diff --git a/website/docs/language/resources/provisioners/remote-exec.mdx b/website/docs/language/resources/provisioners/remote-exec.mdx
index 4b4d94274..89ce5c109 100644
--- a/website/docs/language/resources/provisioners/remote-exec.mdx
+++ b/website/docs/language/resources/provisioners/remote-exec.mdx
@@ -18,8 +18,8 @@ provisioner requires a [connection](/language/resources/provisioners/connection)
 and supports both `ssh` and `winrm`.
 
 -> **Note:** Provisioners should only be used as a last resort. For most
-common situations there are better alternatives. For more information, see
-[the main Provisioners page](/language/resources/provisioners).
+common situations there are better alternatives. Refer to
+[Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Example usage
 
@@ -27,7 +27,7 @@ common situations there are better alternatives. For more information, see
 resource "aws_instance" "web" {
   # ...
 
-  # Establishes connection to be used by all 
+  # Establishes connection to be used by all
   # generic remote provisioners (i.e. file/remote-exec)
   connection {
     type     = "ssh"
diff --git a/website/docs/language/resources/provisioners/salt-masterless.mdx b/website/docs/language/resources/provisioners/salt-masterless.mdx
index 70fd17dbe..45aade11f 100644
--- a/website/docs/language/resources/provisioners/salt-masterless.mdx
+++ b/website/docs/language/resources/provisioners/salt-masterless.mdx
@@ -12,7 +12,8 @@ Type: `salt-masterless`
 The `salt-masterless` Terraform provisioner provisions machines built by Terraform
 using [Salt](http://saltstack.com/) states, without connecting to a Salt master. The `salt-masterless` provisioner supports `ssh` [connections](/language/resources/provisioners/connection).
 
-!> **Note:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. For more information, see [the main Provisioners page](/language/resources/provisioners).
+!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. Refer to
+[Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Requirements
 

From bfefb7405eefdbc8f74e82669148eb1379c0ec73 Mon Sep 17 00:00:00 2001
From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com>
Date: Wed, 5 Jan 2022 11:09:43 -0500
Subject: [PATCH 02/11] Update layout file to remove deleted page

---
 website/layouts/language.erb | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/website/layouts/language.erb b/website/layouts/language.erb
index b2233530f..ee9d01774 100644
--- a/website/layouts/language.erb
+++ b/website/layouts/language.erb
@@ -85,10 +85,6 @@
           <li>
             <a href="#">Provisioners</a>
             <ul class="nav">
-              <li>
-                <a href="/docs/language/resources/provisioners/index.html">Overview</a>
-              </li>
-
               <li>
                 <a href="/docs/language/resources/provisioners/syntax.html">Declaring Provisioners</a>
               </li>

From 5d24146f1748c198f230ec3411d8c1be2ea70248 Mon Sep 17 00:00:00 2001
From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com>
Date: Wed, 5 Jan 2022 11:12:49 -0500
Subject: [PATCH 03/11] Oops edited the wrong layout file

---
 website/layouts/language.erb | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/website/layouts/language.erb b/website/layouts/language.erb
index ee9d01774..b2233530f 100644
--- a/website/layouts/language.erb
+++ b/website/layouts/language.erb
@@ -85,6 +85,10 @@
           <li>
             <a href="#">Provisioners</a>
             <ul class="nav">
+              <li>
+                <a href="/docs/language/resources/provisioners/index.html">Overview</a>
+              </li>
+
               <li>
                 <a href="/docs/language/resources/provisioners/syntax.html">Declaring Provisioners</a>
               </li>

From 5cb8be0d500f16ac5c4c7c02a0e7a9425b734853 Mon Sep 17 00:00:00 2001
From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com>
Date: Wed, 5 Jan 2022 11:13:27 -0500
Subject: [PATCH 04/11] Update nav to remove overview page that no longer
 exists

---
 website/data/language-nav-data.json | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/website/data/language-nav-data.json b/website/data/language-nav-data.json
index 24100696c..3efdda766 100644
--- a/website/data/language-nav-data.json
+++ b/website/data/language-nav-data.json
@@ -74,10 +74,6 @@
       {
         "title": "Provisioners",
         "routes": [
-          {
-            "title": "Overview",
-            "path": "resources/provisioners"
-          },
           {
             "title": "Declaring Provisioners",
             "path": "resources/provisioners/syntax"

From 63106da0b9bc9de334a967516b0a896bbaed0aa8 Mon Sep 17 00:00:00 2001
From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com>
Date: Wed, 5 Jan 2022 11:53:39 -0500
Subject: [PATCH 05/11] Language updates

---
 .../language/resources/provisioners/chef.mdx  |   2 +-
 .../resources/provisioners/connection.mdx     | 135 +++++-------------
 .../language/resources/provisioners/file.mdx  |   3 +-
 .../resources/provisioners/habitat.mdx        |   2 +-
 .../resources/provisioners/null_resource.mdx  |   3 +-
 .../resources/provisioners/puppet.mdx         |   2 +-
 .../resources/provisioners/remote-exec.mdx    |   3 +-
 .../provisioners/salt-masterless.mdx          |   2 +-
 8 files changed, 46 insertions(+), 106 deletions(-)

diff --git a/website/docs/language/resources/provisioners/chef.mdx b/website/docs/language/resources/provisioners/chef.mdx
index 99419c11e..5683b0f69 100644
--- a/website/docs/language/resources/provisioners/chef.mdx
+++ b/website/docs/language/resources/provisioners/chef.mdx
@@ -11,7 +11,7 @@ The `chef` provisioner installs, configures and runs the Chef Client on a remote
 resource. The `chef` provisioner supports both `ssh` and `winrm` type
 [connections](/language/resources/provisioners/connection).
 
-!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. Refer to
+!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. Provisioners should also be a last resort. There are better alternatives for most common situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Requirements
diff --git a/website/docs/language/resources/provisioners/connection.mdx b/website/docs/language/resources/provisioners/connection.mdx
index 22a4c16a0..b958880f2 100644
--- a/website/docs/language/resources/provisioners/connection.mdx
+++ b/website/docs/language/resources/provisioners/connection.mdx
@@ -7,15 +7,16 @@ description: >-
 
 # Provisioner Connection Settings
 
-Most provisioners require access to the remote resource via SSH or WinRM, and
+Most provisioners require access to the remote resource via SSH or WinRM and
 expect a nested `connection` block with details about how to connect.
 
--> **Note:** Provisioners should only be used as a last resort. For most
-common situations there are better alternatives. Refer to
+-> **Note:** Provisioners should only be used as a last resort. There are better alternatives for most common situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Connection Block
 
+You can create one or more `connection` blocks that describe how to access the remote resource. One use case for providing multiple connections is to have an initial provisioner connect as the `root` user to set up user accounts, and then have subsequent provisioners connect as a user with more limited permissions.
+
 Connection blocks don't take a block label, and can be nested within either a
 `resource` or a `provisioner`.
 
@@ -24,15 +25,9 @@ Connection blocks don't take a block label, and can be nested within either a
 * A `connection` block nested in a `provisioner` block only affects that
   provisioner, and overrides any resource-level connection settings.
 
-One use case for providing multiple connections is to have an initial
-provisioner connect as the `root` user to set up user accounts, and have
-subsequent provisioners connect as a user with more limited permissions.
-
 Since the SSH connection type is most often used with
 newly-created remote resources, validation of SSH host keys is disabled by
-default. In scenarios where this is not acceptable, a separate mechanism for
-key distribution could be established and the `host_key` directive documented
-below explicitly set to verify against a specific key or signing CA.
+default. If this is not acceptable, you can establish a separate mechanism for key distribution and explicitly set the `host_key` argument (details below) to verify against a specific key or signing CA.
 
 -> **Note:** In Terraform 0.11 and earlier, providers could set default values
 for some connection settings, so that `connection` blocks could sometimes be
@@ -40,7 +35,7 @@ omitted. This feature was removed in 0.12 in order to make Terraform's behavior
 more predictable.
 
 
-## Example usage
+### Example usage
 
 ```hcl
 # Copies the file as the root user using SSH
@@ -79,67 +74,29 @@ The `self` object represents the connection's parent resource, and has all of
 that resource's attributes. For example, use `self.public_ip` to reference an
 `aws_instance`'s `public_ip` attribute.
 
--> **Technical note:** Resource references are restricted here because
-references create dependencies. Referring to a resource by name within its own
-block would create a dependency cycle.
+Resource references are restricted because references create dependencies. Referring to a resource by name within its own block would create a dependency cycle.
 
 ## Argument Reference
 
-**The following arguments are supported by all connection types:**
-
-* `type` - The connection type that should be used. Valid types are `ssh` and `winrm`.
-  Defaults to `ssh`.
-
-* `user` - The user that we should use for the connection.
-  Defaults to `root` when using type `ssh` and defaults to `Administrator` when using type `winrm`.
-
-* `password` - The password we should use for the connection. In some cases this is
-  specified by the provider.
-
-* `host` - (Required) The address of the resource to connect to.
-
-* `port` - The port to connect to.
-  Defaults to `22` when using type `ssh` and defaults to `5985` when using type `winrm`.
-
-* `timeout` - The timeout to wait for the connection to become available. Should be provided as a string like `30s` or `5m`.
-  Defaults to 5 minutes.
-
-* `script_path` - The path used to copy scripts meant for remote execution.
-  For more information, see
-  [How Provisioners Execute Remote Scripts](#how-provisioners-execute-remote-scripts)
-  below.
-
-**Additional arguments only supported by the `ssh` connection type:**
-
-* `private_key` - The contents of an SSH key to use for the connection. These can
-  be loaded from a file on disk using
-  [the `file` function](/language/functions/file). This takes
-  preference over the password if provided.
-
-* `certificate` - The contents of a signed CA Certificate. The certificate argument must be
-  used in conjunction with a `private_key`. These can
-  be loaded from a file on disk using the [the `file` function](/language/functions/file).
-
-* `agent` - Set to `false` to disable using `ssh-agent` to authenticate. On Windows the
-  only supported SSH authentication agent is
-  [Pageant](http://the.earth.li/\~sgtatham/putty/0.66/htmldoc/Chapter9.html#pageant).
-
-* `agent_identity` - The preferred identity from the ssh agent for authentication.
-
-* `host_key` - The public key from the remote host or the signing CA, used to
-  verify the connection.
-
-* `target_platform` - The target platform to connect to. Valid values are `"windows"` and `"unix"`. Defaults to `"unix"` if not set.
-
-**Additional arguments only supported by the `winrm` connection type:**
-
-* `https` - Set to `true` to connect using HTTPS instead of HTTP.
-
-* `insecure` - Set to `true` to not validate the HTTPS certificate chain.
-
-* `use_ntlm` - Set to `true` to use NTLM authentication, rather than default (basic authentication), removing the requirement for basic authentication to be enabled within the target guest. Further reading for remote connection authentication can be found [here](https://docs.microsoft.com/en-us/windows/win32/winrm/authentication-for-remote-connections?redirectedfrom=MSDN).
-
-* `cacert` - The CA certificate to validate against.
+| Argument Name | Supported By | Description | Default |
+|---------------|--------------|-------------|---------|
+| `type` | Both | The connection type that should be used. Valid types are `"ssh"` and `"winrm"`. | `"ssh"` |
+| `user` | Both | The user to use for the connection. | `root` for type `"ssh"`<br />`Administrator` for type `"winrm"` |
+| `password` | Both | The password we should use for the connection. | |
+| `host` | Both | **Required** - The address of the resource to connect to. | |
+| `port` | Both| The port to connect to. | `22` for type `"ssh"`<br />`5985` for type `"winrm"` |
+| `timeout` | Both | The timeout to wait for the connection to become available. Should be provided as a string like `"30s"` or `"5m"`. | `"5m"` |
+| `script_path` | Both | The path used to copy scripts meant for remote execution. For more information, see [How Provisioners Execute Remote Scripts](#how-provisioners-execute-remote-scripts) below. | (see below)) |
+| `private_key` | SSH | The contents of an SSH key to use for the connection. These can be loaded from a file on disk using [the `file` function](/language/functions/file). This takes preference over `password` if provided. | |
+| `certificate` | SSH | The contents of a signed CA Certificate. The certificate argument must be used in conjunction with a `private_key`. These can be loaded from a file on disk using the [the `file` function](/language/functions/file). | |
+| `agent` | SSH | Set to `false` to disable using `ssh-agent` to authenticate. On Windows the only supported SSH authentication agent is [Pageant](http://the.earth.li/\~sgtatham/putty/0.66/htmldoc/Chapter9.html#pageant). |   |
+| `agent_identity`| SSH | The preferred identity from the ssh agent for authentication. | |
+| `host_key` | SSH | The public key from the remote host or the signing CA, used to verify the connection. | |
+| `target_platform`| SSH | The target platform to connect to. Valid values are `"windows"` and `"unix"`. If the platform is set to `windows`, the default `script_path` is `c:\windows\temp\terraform_%RAND%.cmd`, assuming [the SSH default shell](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_server_configuration#configuring-the-default-shell-for-openssh-in-windows) is `cmd.exe`. If the SSH default shell is PowerShell, set `script_path` to `"c:/windows/temp/terraform_%RAND%.ps1"` | `"unix"` |
+| `https`| WinRM | Set to `true` to connect using HTTPS instead of HTTP. | |
+| `insecure`| WinRM | Set to `true` to not validate skip validating the HTTPS certificate chain. | |
+| `use_ntlm` | WinRM | Set to `true` to use NTLM authentication, rather than default (basic authentication), removing the requirement for basic authentication to be enabled within the target guest. For more information, see [Authentication for Remote Connections](https://docs.microsoft.com/en-us/windows/win32/winrm/authentication-for-remote-connections) in the Windows App Development documentation. | |
+| `cacert` | WinRM | The CA certificate to validate against. | |
 
 Provisioners typically assume that the remote system runs Microsoft Windows
 when using the `winrm` connection type. Behaviors which would vary based on
@@ -150,32 +107,18 @@ Windows-specific behavior when using WinRM, unless otherwise specified.
 
 ## Connecting through a Bastion Host with SSH
 
-The `ssh` connection also supports the following fields to facilitate connnections via a
-[bastion host](https://en.wikipedia.org/wiki/Bastion_host).
+The `ssh` connection also supports the following arguments to connect
+indirectly via a [bastion host](https://en.wikipedia.org/wiki/Bastion_host).
 
-* `bastion_host` - Setting this enables the bastion Host connection. This host
-  will be connected to first, and then the `host` connection will be made from there.
-
-* `bastion_host_key` - The public key from the remote host or the signing CA,
-  used to verify the host connection.
-
-* `bastion_port` - The port to use connect to the bastion host. Defaults to the
-  value of the `port` field.
-
-* `bastion_user` - The user for the connection to the bastion host. Defaults to
-  the value of the `user` field.
-
-* `bastion_password` - The password we should use for the bastion host.
-  Defaults to the value of the `password` field.
-
-* `bastion_private_key` - The contents of an SSH key file to use for the bastion
-  host. These can be loaded from a file on disk using
-  [the `file` function](/language/functions/file).
-  Defaults to the value of the `private_key` field.
-
-* `bastion_certificate` - The contents of a signed CA Certificate. The certificate argument
-  must be used in conjunction with a `bastion_private_key`. These can be loaded from
-  a file on disk using the [the `file` function](/language/functions/file).
+| Argument Name | Description | Default |
+|---------------|-------------|---------|
+| `bastion_host` | Setting this enables the bastion Host connection. The provisioner will connect to `bastion_host` first, and then connect from there to `host`. | |
+| `bastion_host_key` | The public key from the remote host or the signing CA, used to verify the host connection. | |
+| `bastion_port` | The port to use connect to the bastion host. | The value of the `port` field.|
+| `bastion_user`| The user for the connection to the bastion host. | The value of the `user` field. |
+| `bastion_password` | The password to use for the bastion host. | The value of the `password` field. |
+| `bastion_private_key` | The contents of an SSH key file to use for the bastion host. These can be loaded from a file on disk using [the `file` function](language/functions/file). | The value of the `private_key` field. |
+| `bastion_certificate` |  The contents of a signed CA Certificate. The certificate argument must be used in conjunction with a `bastion_private_key`. These can be loaded from a file on disk using the [the `file` function](/language/functions/file). |
 
 ## How Provisioners Execute Remote Scripts
 
@@ -188,7 +131,7 @@ and other context between script statements.
 
 However, this approach does have some consequences which can be relevant in
 some unusual situations, even though this is just an implementation detail
-for typical use.
+in typical use.
 
 Most importantly, there must be a suitable location in the remote filesystem
 where the provisioner can create the script file. By default, Terraform
@@ -219,7 +162,7 @@ As with the default patterns, provisioners will replace the sequence `%RAND%`
 with randomly-selected decimal digits, to reduce the likelihood of collisions
 between multiple provisioners running concurrently.
 
-If your target system is running Windows, we recommend uses forward slashes
+If your target system is running Windows, we recommend using forward slashes
 instead of backslashes, despite the typical convention on Windows, because
 the Terraform language uses backslash as the quoted string escape character.
 
diff --git a/website/docs/language/resources/provisioners/file.mdx b/website/docs/language/resources/provisioners/file.mdx
index 255814cd7..a73291013 100644
--- a/website/docs/language/resources/provisioners/file.mdx
+++ b/website/docs/language/resources/provisioners/file.mdx
@@ -12,8 +12,7 @@ The `file` provisioner is used to copy files or directories from the machine
 executing Terraform to the newly created resource. The `file` provisioner
 supports both `ssh` and `winrm` type [connections](/language/resources/provisioners/connection).
 
--> **Note:** Provisioners should only be used as a last resort. For most
-common situations there are better alternatives. Refer to
+-> **Note:** Provisioners should only be used as a last resort. There are better alternatives for most common situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Example usage
diff --git a/website/docs/language/resources/provisioners/habitat.mdx b/website/docs/language/resources/provisioners/habitat.mdx
index cdd8f8bf9..abbee1db8 100644
--- a/website/docs/language/resources/provisioners/habitat.mdx
+++ b/website/docs/language/resources/provisioners/habitat.mdx
@@ -9,7 +9,7 @@ description: >-
 
 The `habitat` provisioner installs the [Habitat](https://habitat.sh) supervisor and loads configured services. This provisioner only supports Linux targets using the `ssh` connection type at this time.
 
-!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. Refer to
+!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. Provisioners should also be a last resort. There are better alternatives for most common situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Requirements
diff --git a/website/docs/language/resources/provisioners/null_resource.mdx b/website/docs/language/resources/provisioners/null_resource.mdx
index 0ba1294a9..827f435f4 100644
--- a/website/docs/language/resources/provisioners/null_resource.mdx
+++ b/website/docs/language/resources/provisioners/null_resource.mdx
@@ -19,8 +19,7 @@ details](/language/resources/provisioners/connection) on a `null_resource`. You
 use its `triggers` argument and any meta-arguments to control exactly where in
 the dependency graph its provisioners will run.
 
--> **Note:** Provisioners should only be used as a last resort. For most
-common situations there are better alternatives. Refer to
+-> **Note:** Provisioners should only be used as a last resort. There are better alternatives for most common situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Example usage
diff --git a/website/docs/language/resources/provisioners/puppet.mdx b/website/docs/language/resources/provisioners/puppet.mdx
index 5563a369e..72d082516 100644
--- a/website/docs/language/resources/provisioners/puppet.mdx
+++ b/website/docs/language/resources/provisioners/puppet.mdx
@@ -11,7 +11,7 @@ The `puppet` provisioner installs, configures and runs the Puppet agent on a
 remote resource. The `puppet` provisioner supports both `ssh` and `winrm` type
 [connections](/language/resources/provisioners/connection).
 
-!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. Refer to
+!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. Provisioners should also be a last resort. There are better alternatives for most common situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Requirements
diff --git a/website/docs/language/resources/provisioners/remote-exec.mdx b/website/docs/language/resources/provisioners/remote-exec.mdx
index 89ce5c109..646b78068 100644
--- a/website/docs/language/resources/provisioners/remote-exec.mdx
+++ b/website/docs/language/resources/provisioners/remote-exec.mdx
@@ -17,8 +17,7 @@ into a cluster, etc. To invoke a local process, see the `local-exec`
 provisioner requires a [connection](/language/resources/provisioners/connection)
 and supports both `ssh` and `winrm`.
 
--> **Note:** Provisioners should only be used as a last resort. For most
-common situations there are better alternatives. Refer to
+-> **Note:** Provisioners should only be used as a last resort. There are better alternatives for most common situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Example usage
diff --git a/website/docs/language/resources/provisioners/salt-masterless.mdx b/website/docs/language/resources/provisioners/salt-masterless.mdx
index 45aade11f..e3fcf67be 100644
--- a/website/docs/language/resources/provisioners/salt-masterless.mdx
+++ b/website/docs/language/resources/provisioners/salt-masterless.mdx
@@ -12,7 +12,7 @@ Type: `salt-masterless`
 The `salt-masterless` Terraform provisioner provisions machines built by Terraform
 using [Salt](http://saltstack.com/) states, without connecting to a Salt master. The `salt-masterless` provisioner supports `ssh` [connections](/language/resources/provisioners/connection).
 
-!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. Refer to
+!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. Provisioners should also be a last resort. There are better alternatives for most common situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Requirements

From 20e9f30c3d364502ba388a6c10a990917c16db30 Mon Sep 17 00:00:00 2001
From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com>
Date: Wed, 5 Jan 2022 12:02:04 -0500
Subject: [PATCH 06/11] formatting nits

---
 .../docs/language/resources/provisioners/connection.mdx   | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/website/docs/language/resources/provisioners/connection.mdx b/website/docs/language/resources/provisioners/connection.mdx
index b958880f2..107ff6196 100644
--- a/website/docs/language/resources/provisioners/connection.mdx
+++ b/website/docs/language/resources/provisioners/connection.mdx
@@ -90,11 +90,11 @@ Resource references are restricted because references create dependencies. Refer
 | `private_key` | SSH | The contents of an SSH key to use for the connection. These can be loaded from a file on disk using [the `file` function](/language/functions/file). This takes preference over `password` if provided. | |
 | `certificate` | SSH | The contents of a signed CA Certificate. The certificate argument must be used in conjunction with a `private_key`. These can be loaded from a file on disk using the [the `file` function](/language/functions/file). | |
 | `agent` | SSH | Set to `false` to disable using `ssh-agent` to authenticate. On Windows the only supported SSH authentication agent is [Pageant](http://the.earth.li/\~sgtatham/putty/0.66/htmldoc/Chapter9.html#pageant). |   |
-| `agent_identity`| SSH | The preferred identity from the ssh agent for authentication. | |
+| `agent_identity` | SSH | The preferred identity from the ssh agent for authentication. | |
 | `host_key` | SSH | The public key from the remote host or the signing CA, used to verify the connection. | |
-| `target_platform`| SSH | The target platform to connect to. Valid values are `"windows"` and `"unix"`. If the platform is set to `windows`, the default `script_path` is `c:\windows\temp\terraform_%RAND%.cmd`, assuming [the SSH default shell](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_server_configuration#configuring-the-default-shell-for-openssh-in-windows) is `cmd.exe`. If the SSH default shell is PowerShell, set `script_path` to `"c:/windows/temp/terraform_%RAND%.ps1"` | `"unix"` |
-| `https`| WinRM | Set to `true` to connect using HTTPS instead of HTTP. | |
-| `insecure`| WinRM | Set to `true` to not validate skip validating the HTTPS certificate chain. | |
+| `target_platform` | SSH | The target platform to connect to. Valid values are `"windows"` and `"unix"`. If the platform is set to `windows`, the default `script_path` is `c:\windows\temp\terraform_%RAND%.cmd`, assuming [the SSH default shell](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_server_configuration#configuring-the-default-shell-for-openssh-in-windows) is `cmd.exe`. If the SSH default shell is PowerShell, set `script_path` to `"c:/windows/temp/terraform_%RAND%.ps1"` | `"unix"` |
+| `https` | WinRM | Set to `true` to connect using HTTPS instead of HTTP. | |
+| `insecure` | WinRM | Set to `true` to not validate skip validating the HTTPS certificate chain. | |
 | `use_ntlm` | WinRM | Set to `true` to use NTLM authentication, rather than default (basic authentication), removing the requirement for basic authentication to be enabled within the target guest. For more information, see [Authentication for Remote Connections](https://docs.microsoft.com/en-us/windows/win32/winrm/authentication-for-remote-connections) in the Windows App Development documentation. | |
 | `cacert` | WinRM | The CA certificate to validate against. | |
 

From ec17cbaeee44730c23f88c92138b0f1bbf5608da Mon Sep 17 00:00:00 2001
From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com>
Date: Wed, 5 Jan 2022 12:10:01 -0500
Subject: [PATCH 07/11] update additional references to overview page

---
 website/docs/language/resources/index.mdx  | 2 +-
 website/docs/language/resources/syntax.mdx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/website/docs/language/resources/index.mdx b/website/docs/language/resources/index.mdx
index 08921cf75..79df607b1 100644
--- a/website/docs/language/resources/index.mdx
+++ b/website/docs/language/resources/index.mdx
@@ -29,7 +29,7 @@ as DNS records.
   [`provider`](/language/meta-arguments/resource-provider),
   and [`lifecycle`](/language/meta-arguments/lifecycle).
 
-- [Provisioners](/language/resources/provisioners)
+- [Provisioners](/language/resources/provisioners/syntax)
   documents configuring post-creation actions for a resource using the
   `provisioner` and `connection` blocks. Since provisioners are non-declarative
   and potentially unpredictable, we strongly recommend that you treat them as a
diff --git a/website/docs/language/resources/syntax.mdx b/website/docs/language/resources/syntax.mdx
index 259981bfb..485609ca8 100644
--- a/website/docs/language/resources/syntax.mdx
+++ b/website/docs/language/resources/syntax.mdx
@@ -129,7 +129,7 @@ The following meta-arguments are documented on separate pages:
 - [`for_each`, to create multiple instances according to a map, or set of strings](/language/meta-arguments/for_each)
 - [`provider`, for selecting a non-default provider configuration](/language/meta-arguments/resource-provider)
 - [`lifecycle`, for lifecycle customizations](/language/meta-arguments/lifecycle)
-- [`provisioner` and `connection`, for taking extra actions after resource creation](/language/resources/provisioners)
+- [`provisioner`, for taking extra actions after resource creation](/language/resources/provisioners/syntax)
 
 ## Operation Timeouts
 

From 29a4591cf2042b4718cfb29f97c2d0d735ae6117 Mon Sep 17 00:00:00 2001
From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com>
Date: Thu, 20 Jan 2022 10:57:38 -0500
Subject: [PATCH 08/11] Fix warning notes

---
 website/docs/language/resources/provisioners/chef.mdx          | 2 +-
 website/docs/language/resources/provisioners/connection.mdx    | 2 +-
 website/docs/language/resources/provisioners/file.mdx          | 2 +-
 website/docs/language/resources/provisioners/habitat.mdx       | 2 +-
 website/docs/language/resources/provisioners/local-exec.mdx    | 3 +--
 website/docs/language/resources/provisioners/null_resource.mdx | 2 +-
 website/docs/language/resources/provisioners/puppet.mdx        | 2 +-
 website/docs/language/resources/provisioners/remote-exec.mdx   | 2 +-
 .../docs/language/resources/provisioners/salt-masterless.mdx   | 2 +-
 9 files changed, 9 insertions(+), 10 deletions(-)

diff --git a/website/docs/language/resources/provisioners/chef.mdx b/website/docs/language/resources/provisioners/chef.mdx
index 5683b0f69..cf1a2b2a5 100644
--- a/website/docs/language/resources/provisioners/chef.mdx
+++ b/website/docs/language/resources/provisioners/chef.mdx
@@ -11,7 +11,7 @@ The `chef` provisioner installs, configures and runs the Chef Client on a remote
 resource. The `chef` provisioner supports both `ssh` and `winrm` type
 [connections](/language/resources/provisioners/connection).
 
-!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. Provisioners should also be a last resort. There are better alternatives for most common situations. Refer to
+!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. Provisioners should also be a last resort. There are better alternatives for most situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Requirements
diff --git a/website/docs/language/resources/provisioners/connection.mdx b/website/docs/language/resources/provisioners/connection.mdx
index 107ff6196..512ea2900 100644
--- a/website/docs/language/resources/provisioners/connection.mdx
+++ b/website/docs/language/resources/provisioners/connection.mdx
@@ -10,7 +10,7 @@ description: >-
 Most provisioners require access to the remote resource via SSH or WinRM and
 expect a nested `connection` block with details about how to connect.
 
--> **Note:** Provisioners should only be used as a last resort. There are better alternatives for most common situations. Refer to
+~> **Important:** You should only use provisioners as a last resort. There are better alternatives for most situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Connection Block
diff --git a/website/docs/language/resources/provisioners/file.mdx b/website/docs/language/resources/provisioners/file.mdx
index a73291013..7b541363c 100644
--- a/website/docs/language/resources/provisioners/file.mdx
+++ b/website/docs/language/resources/provisioners/file.mdx
@@ -12,7 +12,7 @@ The `file` provisioner is used to copy files or directories from the machine
 executing Terraform to the newly created resource. The `file` provisioner
 supports both `ssh` and `winrm` type [connections](/language/resources/provisioners/connection).
 
--> **Note:** Provisioners should only be used as a last resort. There are better alternatives for most common situations. Refer to
+~> **Important:** You should only use provisioners as a last resort. There are better alternatives for most situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Example usage
diff --git a/website/docs/language/resources/provisioners/habitat.mdx b/website/docs/language/resources/provisioners/habitat.mdx
index abbee1db8..9d5b74774 100644
--- a/website/docs/language/resources/provisioners/habitat.mdx
+++ b/website/docs/language/resources/provisioners/habitat.mdx
@@ -9,7 +9,7 @@ description: >-
 
 The `habitat` provisioner installs the [Habitat](https://habitat.sh) supervisor and loads configured services. This provisioner only supports Linux targets using the `ssh` connection type at this time.
 
-!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. Provisioners should also be a last resort. There are better alternatives for most common situations. Refer to
+!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. Provisioners should also be a last resort. There are better alternatives for most situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Requirements
diff --git a/website/docs/language/resources/provisioners/local-exec.mdx b/website/docs/language/resources/provisioners/local-exec.mdx
index 8298cfbe7..dee5d2081 100644
--- a/website/docs/language/resources/provisioners/local-exec.mdx
+++ b/website/docs/language/resources/provisioners/local-exec.mdx
@@ -18,8 +18,7 @@ Note that even though the resource will be fully created when the provisioner is
 run, there is no guarantee that it will be in an operable state - for example
 system services such as `sshd` may not be started yet on compute resources.
 
--> **Note:** Provisioners should only be used as a last resort. For most
-common situations there are better alternatives. Refer to
+~> **Important:** You should only use provisioners as a last resort. There are better alternatives for most situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Example usage
diff --git a/website/docs/language/resources/provisioners/null_resource.mdx b/website/docs/language/resources/provisioners/null_resource.mdx
index 827f435f4..cf4218086 100644
--- a/website/docs/language/resources/provisioners/null_resource.mdx
+++ b/website/docs/language/resources/provisioners/null_resource.mdx
@@ -19,7 +19,7 @@ details](/language/resources/provisioners/connection) on a `null_resource`. You
 use its `triggers` argument and any meta-arguments to control exactly where in
 the dependency graph its provisioners will run.
 
--> **Note:** Provisioners should only be used as a last resort. There are better alternatives for most common situations. Refer to
+~> **Important:** You should only use provisioners as a last resort. There are better alternatives for most situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Example usage
diff --git a/website/docs/language/resources/provisioners/puppet.mdx b/website/docs/language/resources/provisioners/puppet.mdx
index 72d082516..3199caf28 100644
--- a/website/docs/language/resources/provisioners/puppet.mdx
+++ b/website/docs/language/resources/provisioners/puppet.mdx
@@ -11,7 +11,7 @@ The `puppet` provisioner installs, configures and runs the Puppet agent on a
 remote resource. The `puppet` provisioner supports both `ssh` and `winrm` type
 [connections](/language/resources/provisioners/connection).
 
-!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. Provisioners should also be a last resort. There are better alternatives for most common situations. Refer to
+!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. Provisioners should also be a last resort. There are better alternatives for most situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Requirements
diff --git a/website/docs/language/resources/provisioners/remote-exec.mdx b/website/docs/language/resources/provisioners/remote-exec.mdx
index 646b78068..dc96b1760 100644
--- a/website/docs/language/resources/provisioners/remote-exec.mdx
+++ b/website/docs/language/resources/provisioners/remote-exec.mdx
@@ -17,7 +17,7 @@ into a cluster, etc. To invoke a local process, see the `local-exec`
 provisioner requires a [connection](/language/resources/provisioners/connection)
 and supports both `ssh` and `winrm`.
 
--> **Note:** Provisioners should only be used as a last resort. There are better alternatives for most common situations. Refer to
+~> **Important:** You should only use provisioners as a last resort. There are better alternatives for most situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Example usage
diff --git a/website/docs/language/resources/provisioners/salt-masterless.mdx b/website/docs/language/resources/provisioners/salt-masterless.mdx
index e3fcf67be..fbe54fed0 100644
--- a/website/docs/language/resources/provisioners/salt-masterless.mdx
+++ b/website/docs/language/resources/provisioners/salt-masterless.mdx
@@ -12,7 +12,7 @@ Type: `salt-masterless`
 The `salt-masterless` Terraform provisioner provisions machines built by Terraform
 using [Salt](http://saltstack.com/) states, without connecting to a Salt master. The `salt-masterless` provisioner supports `ssh` [connections](/language/resources/provisioners/connection).
 
-!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. Provisioners should also be a last resort. There are better alternatives for most common situations. Refer to
+!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. Provisioners should also be a last resort. There are better alternatives for most situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Requirements

From 1d53273b7a7b945a3dc681d0f4632255fd937236 Mon Sep 17 00:00:00 2001
From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com>
Date: Thu, 20 Jan 2022 11:28:52 -0500
Subject: [PATCH 09/11] Language nits

---
 .../resources/provisioners/connection.mdx     | 44 +++++++++----------
 1 file changed, 20 insertions(+), 24 deletions(-)

diff --git a/website/docs/language/resources/provisioners/connection.mdx b/website/docs/language/resources/provisioners/connection.mdx
index 512ea2900..5b3d275ee 100644
--- a/website/docs/language/resources/provisioners/connection.mdx
+++ b/website/docs/language/resources/provisioners/connection.mdx
@@ -15,15 +15,15 @@ expect a nested `connection` block with details about how to connect.
 
 ## Connection Block
 
-You can create one or more `connection` blocks that describe how to access the remote resource. One use case for providing multiple connections is to have an initial provisioner connect as the `root` user to set up user accounts, and then have subsequent provisioners connect as a user with more limited permissions.
+You can create one or more `connection` blocks that describe how to access the remote resource. One use case for providing multiple connections is to have an initial provisioner connect as the `root` user to set up user accounts and then have subsequent provisioners connect as a user with more limited permissions.
 
-Connection blocks don't take a block label, and can be nested within either a
+Connection blocks don't take a block label and can be nested within either a
 `resource` or a `provisioner`.
 
 * A `connection` block nested directly within a `resource` affects all of
   that resource's provisioners.
 * A `connection` block nested in a `provisioner` block only affects that
-  provisioner, and overrides any resource-level connection settings.
+  provisioner and overrides any resource-level connection settings.
 
 Since the SSH connection type is most often used with
 newly-created remote resources, validation of SSH host keys is disabled by
@@ -65,28 +65,28 @@ provisioner "file" {
 }
 ```
 
-## The `self` Object
+### The `self` Object
 
-Expressions in `connection` blocks cannot refer to their parent resource by
-name. Instead, they can use the special `self` object.
+Expressions in `connection` blocks cannot refer to their parent resource by name. References create dependencies, and referring to a resource by name within its own block would create a dependency cycle. Instead, expressions can use the `self` object, which represents the connection's parent resource and has all of that resource's attributes. For example, use `self.public_ip` to reference an `aws_instance`'s `public_ip` attribute.
 
-The `self` object represents the connection's parent resource, and has all of
-that resource's attributes. For example, use `self.public_ip` to reference an
-`aws_instance`'s `public_ip` attribute.
 
-Resource references are restricted because references create dependencies. Referring to a resource by name within its own block would create a dependency cycle.
+### Argument Reference
 
-## Argument Reference
+The `connection` block supports the following argments. Some arguments are only supported by either the SSH or the WinRM connection type.
 
-| Argument Name | Supported By | Description | Default |
+Behaviors which would vary based on
+the `target_platform` option if using SSH will instead force the
+Windows-specific behavior when using WinRM, unless otherwise specified.
+
+| Argument | Connection Type | Description | Default |
 |---------------|--------------|-------------|---------|
-| `type` | Both | The connection type that should be used. Valid types are `"ssh"` and `"winrm"`. | `"ssh"` |
+| `type` | Both | The connection type. Valid values are `"ssh"` and `"winrm"`. Provisioners typically assume that the remote system runs Microsoft Windows when using the `"winrm"` connection type. | `"ssh"` |
 | `user` | Both | The user to use for the connection. | `root` for type `"ssh"`<br />`Administrator` for type `"winrm"` |
-| `password` | Both | The password we should use for the connection. | |
+| `password` | Both | The password to use for the connection. | |
 | `host` | Both | **Required** - The address of the resource to connect to. | |
 | `port` | Both| The port to connect to. | `22` for type `"ssh"`<br />`5985` for type `"winrm"` |
-| `timeout` | Both | The timeout to wait for the connection to become available. Should be provided as a string like `"30s"` or `"5m"`. | `"5m"` |
-| `script_path` | Both | The path used to copy scripts meant for remote execution. For more information, see [How Provisioners Execute Remote Scripts](#how-provisioners-execute-remote-scripts) below. | (see below)) |
+| `timeout` | Both | The timeout to wait for the connection to become available. Should be provided as a string (e.g., `"30s"` or `"5m"`.) | `"5m"` |
+| `script_path` | Both | The path used to copy scripts meant for remote execution. Refer to [How Provisioners Execute Remote Scripts](#how-provisioners-execute-remote-scripts) below for more details. | (details below) |
 | `private_key` | SSH | The contents of an SSH key to use for the connection. These can be loaded from a file on disk using [the `file` function](/language/functions/file). This takes preference over `password` if provided. | |
 | `certificate` | SSH | The contents of a signed CA Certificate. The certificate argument must be used in conjunction with a `private_key`. These can be loaded from a file on disk using the [the `file` function](/language/functions/file). | |
 | `agent` | SSH | Set to `false` to disable using `ssh-agent` to authenticate. On Windows the only supported SSH authentication agent is [Pageant](http://the.earth.li/\~sgtatham/putty/0.66/htmldoc/Chapter9.html#pageant). |   |
@@ -94,23 +94,19 @@ Resource references are restricted because references create dependencies. Refer
 | `host_key` | SSH | The public key from the remote host or the signing CA, used to verify the connection. | |
 | `target_platform` | SSH | The target platform to connect to. Valid values are `"windows"` and `"unix"`. If the platform is set to `windows`, the default `script_path` is `c:\windows\temp\terraform_%RAND%.cmd`, assuming [the SSH default shell](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_server_configuration#configuring-the-default-shell-for-openssh-in-windows) is `cmd.exe`. If the SSH default shell is PowerShell, set `script_path` to `"c:/windows/temp/terraform_%RAND%.ps1"` | `"unix"` |
 | `https` | WinRM | Set to `true` to connect using HTTPS instead of HTTP. | |
-| `insecure` | WinRM | Set to `true` to not validate skip validating the HTTPS certificate chain. | |
-| `use_ntlm` | WinRM | Set to `true` to use NTLM authentication, rather than default (basic authentication), removing the requirement for basic authentication to be enabled within the target guest. For more information, see [Authentication for Remote Connections](https://docs.microsoft.com/en-us/windows/win32/winrm/authentication-for-remote-connections) in the Windows App Development documentation. | |
+| `insecure` | WinRM | Set to `true` to skip validating the HTTPS certificate chain. | |
+| `use_ntlm` | WinRM | Set to `true` to use NTLM authentication rather than default (basic authentication), removing the requirement for basic authentication to be enabled within the target guest. Refer to [Authentication for Remote Connections](https://docs.microsoft.com/en-us/windows/win32/winrm/authentication-for-remote-connections) in the Windows App Development documentation for more details. | |
 | `cacert` | WinRM | The CA certificate to validate against. | |
 
-Provisioners typically assume that the remote system runs Microsoft Windows
-when using the `winrm` connection type. Behaviors which would vary based on
-the `target_platform` option if using SSH will instead force the
-Windows-specific behavior when using WinRM, unless otherwise specified.
 
 <a id="bastion"></a>
 
 ## Connecting through a Bastion Host with SSH
 
 The `ssh` connection also supports the following arguments to connect
-indirectly via a [bastion host](https://en.wikipedia.org/wiki/Bastion_host).
+indirectly with a [bastion host](https://en.wikipedia.org/wiki/Bastion_host).
 
-| Argument Name | Description | Default |
+| Argument | Description | Default |
 |---------------|-------------|---------|
 | `bastion_host` | Setting this enables the bastion Host connection. The provisioner will connect to `bastion_host` first, and then connect from there to `host`. | |
 | `bastion_host_key` | The public key from the remote host or the signing CA, used to verify the host connection. | |

From 9f4c4ff093828b5ba54e9bd8a58c5dd07ad6a95c Mon Sep 17 00:00:00 2001
From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com>
Date: Fri, 21 Jan 2022 10:48:27 -0500
Subject: [PATCH 10/11] Update note to be more direct :)

---
 website/docs/language/resources/provisioners/connection.mdx    | 2 +-
 website/docs/language/resources/provisioners/file.mdx          | 2 +-
 website/docs/language/resources/provisioners/local-exec.mdx    | 2 +-
 website/docs/language/resources/provisioners/null_resource.mdx | 2 +-
 website/docs/language/resources/provisioners/remote-exec.mdx   | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/website/docs/language/resources/provisioners/connection.mdx b/website/docs/language/resources/provisioners/connection.mdx
index 5b3d275ee..736d4eab3 100644
--- a/website/docs/language/resources/provisioners/connection.mdx
+++ b/website/docs/language/resources/provisioners/connection.mdx
@@ -10,7 +10,7 @@ description: >-
 Most provisioners require access to the remote resource via SSH or WinRM and
 expect a nested `connection` block with details about how to connect.
 
-~> **Important:** You should only use provisioners as a last resort. There are better alternatives for most situations. Refer to
+~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Connection Block
diff --git a/website/docs/language/resources/provisioners/file.mdx b/website/docs/language/resources/provisioners/file.mdx
index 7b541363c..8d8b2ac04 100644
--- a/website/docs/language/resources/provisioners/file.mdx
+++ b/website/docs/language/resources/provisioners/file.mdx
@@ -12,7 +12,7 @@ The `file` provisioner is used to copy files or directories from the machine
 executing Terraform to the newly created resource. The `file` provisioner
 supports both `ssh` and `winrm` type [connections](/language/resources/provisioners/connection).
 
-~> **Important:** You should only use provisioners as a last resort. There are better alternatives for most situations. Refer to
+~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Example usage
diff --git a/website/docs/language/resources/provisioners/local-exec.mdx b/website/docs/language/resources/provisioners/local-exec.mdx
index dee5d2081..eda7f9ad0 100644
--- a/website/docs/language/resources/provisioners/local-exec.mdx
+++ b/website/docs/language/resources/provisioners/local-exec.mdx
@@ -18,7 +18,7 @@ Note that even though the resource will be fully created when the provisioner is
 run, there is no guarantee that it will be in an operable state - for example
 system services such as `sshd` may not be started yet on compute resources.
 
-~> **Important:** You should only use provisioners as a last resort. There are better alternatives for most situations. Refer to
+~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Example usage
diff --git a/website/docs/language/resources/provisioners/null_resource.mdx b/website/docs/language/resources/provisioners/null_resource.mdx
index cf4218086..fc270e364 100644
--- a/website/docs/language/resources/provisioners/null_resource.mdx
+++ b/website/docs/language/resources/provisioners/null_resource.mdx
@@ -19,7 +19,7 @@ details](/language/resources/provisioners/connection) on a `null_resource`. You
 use its `triggers` argument and any meta-arguments to control exactly where in
 the dependency graph its provisioners will run.
 
-~> **Important:** You should only use provisioners as a last resort. There are better alternatives for most situations. Refer to
+~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Example usage
diff --git a/website/docs/language/resources/provisioners/remote-exec.mdx b/website/docs/language/resources/provisioners/remote-exec.mdx
index dc96b1760..769ba72de 100644
--- a/website/docs/language/resources/provisioners/remote-exec.mdx
+++ b/website/docs/language/resources/provisioners/remote-exec.mdx
@@ -17,7 +17,7 @@ into a cluster, etc. To invoke a local process, see the `local-exec`
 provisioner requires a [connection](/language/resources/provisioners/connection)
 and supports both `ssh` and `winrm`.
 
-~> **Important:** You should only use provisioners as a last resort. There are better alternatives for most situations. Refer to
+~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to
 [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
 
 ## Example usage

From 20e740ef8830d211396a8d5e1b7bf284a441d665 Mon Sep 17 00:00:00 2001
From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com>
Date: Fri, 21 Jan 2022 11:01:37 -0500
Subject: [PATCH 11/11] Final formatting and langauge nits

---
 .../docs/language/resources/provisioners/connection.mdx    | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/website/docs/language/resources/provisioners/connection.mdx b/website/docs/language/resources/provisioners/connection.mdx
index 736d4eab3..987ac7892 100644
--- a/website/docs/language/resources/provisioners/connection.mdx
+++ b/website/docs/language/resources/provisioners/connection.mdx
@@ -74,13 +74,10 @@ Expressions in `connection` blocks cannot refer to their parent resource by name
 
 The `connection` block supports the following argments. Some arguments are only supported by either the SSH or the WinRM connection type.
 
-Behaviors which would vary based on
-the `target_platform` option if using SSH will instead force the
-Windows-specific behavior when using WinRM, unless otherwise specified.
 
 | Argument | Connection Type | Description | Default |
 |---------------|--------------|-------------|---------|
-| `type` | Both | The connection type. Valid values are `"ssh"` and `"winrm"`. Provisioners typically assume that the remote system runs Microsoft Windows when using the `"winrm"` connection type. | `"ssh"` |
+| `type` | Both | The connection type. Valid values are `"ssh"` and `"winrm"`. Provisioners typically assume that the remote system runs Microsoft Windows when using WinRM. Behaviors based on the SSH `target_platform` will force Windows-specific behavior for WinRM, unless otherwise specified.| `"ssh"` |
 | `user` | Both | The user to use for the connection. | `root` for type `"ssh"`<br />`Administrator` for type `"winrm"` |
 | `password` | Both | The password to use for the connection. | |
 | `host` | Both | **Required** - The address of the resource to connect to. | |
@@ -182,7 +179,7 @@ connection {
 }
 ```
 
--> **Warning:** In Terraform v1.0 and earlier, the built-in provisioners
+!> **Warning:** In Terraform v1.0 and earlier, the built-in provisioners
 incorrectly passed the `script_path` value to `scp` through a remote shell and
 thus allowed it to be subject to arbitrary shell expansion, and thus created an
 unintended opportunity for remote code execution. Terraform v1.1 and later