docs: update org units resource and data source (#1642)

docs/data-sources/organizational_unit.md

@@ -3,19 +3,19 @@
 page_title: "aiven_organizational_unit Data Source - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  The Organizational Unit data source provides information about the existing Aiven Organizational Unit.
+  Gets information about an organizational unit.
 ---
 
 # aiven_organizational_unit (Data Source)
 
-The Organizational Unit data source provides information about the existing Aiven Organizational Unit.
+Gets information about an organizational unit.
 
 ## Example Usage
 
 ```terraform
-data "aiven_organizational_unit" "organizational_unit1" {
-  name      = "<ORGANIZATIONAL_UNIT_NAME>"
-  parent_id = "<ORGANIZATION_ID>"
+data "aiven_organizational_unit" "example_unit" {
+  name      = "Example organizational unit"
+  parent_id = aiven_organization.main.id
 }
 ```
 
@@ -24,12 +24,12 @@ data "aiven_organizational_unit" "organizational_unit1" {
 
 ### Required
 
-- `name` (String) Organizational Unit name
+- `name` (String) The name of the organizational unit.
 
 ### Read-Only
 
-- `create_time` (String) Time of creation
+- `create_time` (String) Time of creation.
 - `id` (String) The ID of this resource.
-- `parent_id` (String) Parent ID
-- `tenant_id` (String) Tenant ID
-- `update_time` (String) Time of last update
+- `parent_id` (String) The ID of the organization that the unit is created in.
+- `tenant_id` (String) Tenant ID.
+- `update_time` (String) Time of last update.

docs/resources/organizational_unit.md

@@ -3,19 +3,19 @@
 page_title: "aiven_organizational_unit Resource - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  The Organizational Unit resource allows the creation and management of Aiven Organizational Units.
+  Creates and manages an organizational unit https://aiven.io/docs/platform/concepts/projects_accounts_access in an Aiven organization.
 ---
 
 # aiven_organizational_unit (Resource)
 
-The Organizational Unit resource allows the creation and management of Aiven Organizational Units.
+Creates and manages an [organizational unit](https://aiven.io/docs/platform/concepts/projects_accounts_access) in an Aiven organization.
 
 ## Example Usage
 
 ```terraform
-resource "aiven_organizational_unit" "organizational_unit1" {
-  name      = "<ORGANIZATIONAL_UNIT_NAME>"
-  parent_id = "<ORGANIZATION_ID>"
+resource "aiven_organizational_unit" "example_unit" {
+  name      = "Example organizational unit"
+  parent_id = aiven_organization.main.id
 }
 ```
 
@@ -24,19 +24,19 @@ resource "aiven_organizational_unit" "organizational_unit1" {
 
 ### Required
 
-- `name` (String) Organizational Unit name
-- `parent_id` (String) Parent ID
+- `name` (String) The name of the organizational unit.
+- `parent_id` (String) The ID of the organization that the unit is created in.
 
 ### Optional
 
 - `timeouts` (Block, Optional) (see [below for nested schema](#nestedblock--timeouts))
 
 ### Read-Only
 
-- `create_time` (String) Time of creation
+- `create_time` (String) Time of creation.
 - `id` (String) The ID of this resource.
-- `tenant_id` (String) Tenant ID
-- `update_time` (String) Time of last update
+- `tenant_id` (String) Tenant ID.
+- `update_time` (String) Time of last update.
 
 <a id="nestedblock--timeouts"></a>
 ### Nested Schema for `timeouts`
@@ -54,5 +54,5 @@ Optional:
 Import is supported using the following syntax:
 
 ```shell
-terraform import aiven_organizational_unit.organizational_unit1 organizational_unit_id
+terraform import aiven_organizational_unit.example_unit ORGANIZATIONAL_UNIT_ID
 ```

examples/data-sources/aiven_organizational_unit/data-source.tf

@@ -1,4 +1,4 @@
-data "aiven_organizational_unit" "organizational_unit1" {
-  name      = "<ORGANIZATIONAL_UNIT_NAME>"
-  parent_id = "<ORGANIZATION_ID>"
+data "aiven_organizational_unit" "example_unit" {
+  name      = "Example organizational unit"
+  parent_id = aiven_organization.main.id
 }

examples/resources/aiven_organizational_unit/import.sh

@@ -1 +1 @@
-terraform import aiven_organizational_unit.organizational_unit1 organizational_unit_id
+terraform import aiven_organizational_unit.example_unit ORGANIZATIONAL_UNIT_ID

examples/resources/aiven_organizational_unit/resource.tf

@@ -1,4 +1,4 @@
-resource "aiven_organizational_unit" "organizational_unit1" {
-  name      = "<ORGANIZATIONAL_UNIT_NAME>"
-  parent_id = "<ORGANIZATION_ID>"
+resource "aiven_organizational_unit" "example_unit" {
+  name      = "Example organizational unit"
+  parent_id = aiven_organization.main.id
 }

internal/sdkprovider/service/organization/organizational_unit.go

@@ -14,34 +14,33 @@ var aivenOrganizationalUnitSchema = map[string]*schema.Schema{
 	"name": {
 		Type:        schema.TypeString,
 		Required:    true,
-		Description: "Organizational Unit name",
+		Description: "The name of the organizational unit.",
 	},
 	"parent_id": {
 		Type:        schema.TypeString,
 		Required:    true,
-		Description: "Parent ID",
+		Description: "The ID of the organization that the unit is created in.",
 	},
 	"tenant_id": {
 		Type:        schema.TypeString,
 		Computed:    true,
-		Description: "Tenant ID",
+		Description: "Tenant ID.",
 	},
 	"create_time": {
 		Type:        schema.TypeString,
 		Computed:    true,
-		Description: "Time of creation",
+		Description: "Time of creation.",
 	},
 	"update_time": {
 		Type:        schema.TypeString,
 		Computed:    true,
-		Description: "Time of last update",
+		Description: "Time of last update.",
 	},
 }
 
 func ResourceOrganizationalUnit() *schema.Resource {
 	return &schema.Resource{
-		Description: "The Organizational Unit resource allows the creation and management of Aiven Organizational " +
-			"Units.",
+		Description:   "Creates and manages an [organizational unit](https://aiven.io/docs/platform/concepts/projects_accounts_access) in an Aiven organization.",
 		CreateContext: resourceOrganizationalUnitCreate,
 		ReadContext:   resourceOrganizationalUnitRead,
 		UpdateContext: resourceOrganizationalUnitUpdate,

internal/sdkprovider/service/organization/organizational_unit_data_source.go

@@ -13,9 +13,8 @@ import (
 func DatasourceOrganizationalUnit() *schema.Resource {
 	return &schema.Resource{
 		ReadContext: datasourceOrganizationalUnitRead,
-		Description: "The Organizational Unit data source provides information about the existing Aiven " +
-			"Organizational Unit.",
-		Schema: schemautil.ResourceSchemaAsDatasourceSchema(aivenOrganizationalUnitSchema, "name"),
+		Description: "Gets information about an organizational unit.",
+		Schema:      schemautil.ResourceSchemaAsDatasourceSchema(aivenOrganizationalUnitSchema, "name"),
 	}
 }