Improve agent_pool_allowed_workspaces docs

Author: brandonc

website/docs/r/agent_pool_allowed_workspaces.html.markdown

@@ -7,22 +7,23 @@ description: |-
 
 # tfe_agent_pool_allowed_workspaces
 
-Adds and removes allowed workspaces on an agent pool
+Adds and removes allowed workspaces on an agent pool.
 
 ~> **NOTE:** This resource requires using the provider with Terraform Cloud and a Terraform Cloud
 for Business account.
 [Learn more about Terraform Cloud pricing here](https://www.hashicorp.com/products/terraform/pricing).
 
 ## Example Usage
 
-Basic usage:
+In this example, the agent pool and workspace are connected through other resources that manage the agent pool permissions as well as the workspace execution mode. Notice that the `tfe_workspace_settings` uses the agent pool reference found in `tfe_agent_pool_allowed_workspaces` in order to create the permission to use the agent pool before assigning it.
 
 ```hcl
 resource "tfe_organization" "test-organization" {
   name  = "my-org-name"
   email = "[email protected]"
 }
 
+// Ensure workspace and agent pool are create first
 resource "tfe_workspace" "test-workspace" {
   name         = "my-workspace-name"
   organization = tfe_organization.test-organization.name
@@ -34,9 +35,18 @@ resource "tfe_agent_pool" "test-agent-pool" {
   organization_scoped = false
 }
 
-resource "tfe_agent_pool_allowed_workspaces" "test-allowed-workspaces" {
+// Ensure permissions are assigned second
+resource "tfe_agent_pool_allowed_workspaces" "allowed" {
   agent_pool_id         = tfe_agent_pool.test-agent-pool.id
-  allowed_workspace_ids = [tfe_workspace.test-workspace.id]
+  allowed_workspace_ids = [for key, value in tfe_workspace.test.*.id : value]
+}
+
+// Lastly, ensure the workspace agent execution is assigned last by
+// referencing allowed_workspaces
+resource "tfe_workspace_settings" "test-workspace-settings" {
+  workspace_id   = tfe_workspace.test-workspace.id
+  execution_mode = "agent"
+  agent_pool_id  = tfe_agent_pool_allowed_workspaces.allowed.id
 }
 ```
 
@@ -55,4 +65,3 @@ A resource can be imported; use `<AGENT POOL ID>` as the import ID. For example:
 ```shell
 terraform import tfe_agent_pool_allowed_workspaces.foobar apool-rW0KoLSlnuNb5adB
 ```
-