Update docs/resources/space.md

Co-authored-by: Sandy Lai <[email protected]>
Signed-off-by: Johnny Winn <[email protected]>

Update docs/resources/space.md

Co-authored-by: Sandy Lai <[email protected]>
Signed-off-by: Johnny Winn <[email protected]>

Update docs/resources/space.md

Co-authored-by: Sandy Lai <[email protected]>
Signed-off-by: Johnny Winn <[email protected]>

Update docs/resources/space.md

Co-authored-by: Sandy Lai <[email protected]>
Signed-off-by: Johnny Winn <[email protected]>

Update docs/resources/space.md

Co-authored-by: Sandy Lai <[email protected]>
Signed-off-by: Johnny Winn <[email protected]>

Update docs/resources/space.md

Co-authored-by: Sandy Lai <[email protected]>
Signed-off-by: Johnny Winn <[email protected]>

Update docs/resources/space.md

Co-authored-by: Sandy Lai <[email protected]>
Signed-off-by: Johnny Winn <[email protected]>

Update docs/resources/space.md

Co-authored-by: Sandy Lai <[email protected]>
Signed-off-by: Johnny Winn <[email protected]>

Update docs/resources/space.md

Co-authored-by: Sandy Lai <[email protected]>
Signed-off-by: Johnny Winn <[email protected]>

Update docs/resources/space.md

Co-authored-by: Sandy Lai <[email protected]>
Signed-off-by: Johnny Winn <[email protected]>

Update docs/resources/space.md

Co-authored-by: Sandy Lai <[email protected]>
Signed-off-by: Johnny Winn <[email protected]>

Update heroku/resource_heroku_space.go

Co-authored-by: Sandy Lai <[email protected]>
Signed-off-by: Johnny Winn <[email protected]>

Update docs/resources/space.md

Co-authored-by: Sandy Lai <[email protected]>
Signed-off-by: Johnny Winn <[email protected]>

Author: heroku-johnny

docs/resources/space.md

@@ -10,34 +10,35 @@ description: |-
 
 Provides a Heroku Private Space resource for running apps in isolated, highly available, secure app execution environments.
 
-Heroku Private Spaces support two generations:
+Both generations of the Heroku platform offer Private Spaces:
 
-* **Cedar** (default): The original generation supporting all Private Space features including Shield spaces
-* **Fir**: The next-generation platform with enhanced capabilities for Cloud Native Buildpacks (CNB), but with some feature limitations
+* **Cedar** (default): The [Cedar generation](https://devcenter.heroku.com/articles/private-spaces#additional-features-for-cedar-private-spaces) supports all Private Space features, including Shield spaces.
+* ```
+* **Fir**: The next-generation platform supports enhanced capabilities for Cloud Native Buildpacks (CNB), but with has some [feature limitations](https://devcenter.heroku.com/articles/generations?preview=1#feature-parity) compared to Cedar Private Spaces.
 
-~> **Note:** The `generation` parameter cannot be changed after space creation. Choose carefully based on your application requirements.
+~> **Note:** You can't change the `generation` parameter after space creation. Choose carefully based on your application requirements.
 
 ## Example Usage
 
 A Heroku "team" was originally called an "organization", and that is still 
 the identifier used in this resource.
 
 ```hcl-terraform
-// Create a new Cedar generation space (default)
+// Create a new Cedar-generation space (default)
 resource "heroku_space" "cedar_space" {
   name = "test-cedar-space"
   organization = "my-company"
   region = "virginia"
-  shield = true  // Cedar supports shield spaces
+  shield = true  // Cedar supports Shield spaces
 }
 
-// Create a new Fir generation space
+// Create a new Fir-generation space
 resource "heroku_space" "fir_space" {
   name = "test-fir-space"
   organization = "my-company"
   region = "virginia"
   generation = "fir"
-  // Note: Fir generation does not support shield spaces
+  // Note: Shield spaces are unavailable for the Fir generation.
 }
 
 // Create a new Heroku app in test-space, same region
@@ -57,13 +58,13 @@ The following arguments are supported:
 
 * `name` - (Required) The name of the Private Space.
 * `organization` - (Required) The name of the Heroku Team which will own the Private Space.
-* `generation` - (Optional) The generation of the Private Space. Valid values are `cedar` and `fir`. Defaults to `cedar` for backward compatibility. Cannot be changed after creation.
+* `generation` - (Optional) The generation of the Heroku platform for the space. Valid values are `cedar` and `fir`. Defaults to `cedar` for backward compatibility. It can't be changed after space creation.
 * `cidr` - (Optional) The RFC-1918 CIDR the Private Space will use.
   It must be a /16 in 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16
 * `data_cidr` - (Optional) The RFC-1918 CIDR that the Private Space will use for the Heroku-managed peering connection
   that's automatically created when using Heroku Data add-ons. It must be between a /16 and a /20
-* `region` - (Optional) provision in a specific [Private Spaces region](https://devcenter.heroku.com/articles/regions#viewing-available-regions).
-* `shield` - (Optional) provision as a [Shield Private Space](https://devcenter.heroku.com/articles/private-spaces#shield-private-spaces). Note: Shield spaces are only supported for `cedar` generation.
+* `region` - (Optional) The [region](https://devcenter.heroku.com/articles/regions#viewing-available-regions) to provision a space in.
+* `shield` - (Optional) `true` if provisioning as a [Shield Private Space](https://devcenter.heroku.com/articles/private-spaces#shield-private-spaces). Note: Shield spaces are only supported for the `cedar` generation.
 
 ## Attributes Reference
 
@@ -72,7 +73,7 @@ The following attributes are exported:
 * `id` - The ID (UUID) of the space.
 * `name` - The space's name.
 * `organization` - The space's Heroku Team.
-* `generation` - The space's generation (`cedar` or `fir`).
+* `generation` - The generation of the Heroku platform for the space (`cedar` or `fir`).
 * `region` - The space's region.
 * `cidr` - The space's CIDR.
 * `data_cidr` - The space's Data CIDR.

heroku/resource_heroku_space.go

@@ -171,7 +171,7 @@ func resourceHerokuSpaceRead(d *schema.ResourceData, meta interface{}) error {
 	}
 	generationStr := generation.(string)
 	if space.Shield && !IsFeatureSupported(generationStr, "space", "shield") {
-		tflog.Warn(context.TODO(), fmt.Sprintf("Space has shield enabled but shield is not supported for %s generation", generationStr))
+		tflog.Warn(context.TODO(), fmt.Sprintf("Space has `shield` set to `true` but Shield spaces are unsupported for the %s generation", generationStr))
 	}
 
 	log.Printf("[DEBUG] Set NAT source IPs to %s for %s", space.NAT.Sources, d.Id())