diff --git a/docs/resources/port_action.md b/docs/resources/port_action.md
index 419f23b5..6e64dd9b 100644
--- a/docs/resources/port_action.md
+++ b/docs/resources/port_action.md
@@ -223,7 +223,7 @@ Required:
 
 Optional:
 
-- `payload` (String) The Azure Devops workflow payload (array or object encoded to a string)
+- `payload` (String) The Azure Devops workflow [payload](https://docs.getport.io/create-self-service-experiences/setup-backend/#define-the-actions-payload) should be in `JSON` format, encoded as a string. Use [jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode) to encode arrays or objects. Learn about how to [define the action payload](https://docs.getport.io/create-self-service-experiences/setup-backend/#define-the-actions-payload).
 
 
 <a id="nestedatt--github_method"></a>
@@ -238,7 +238,7 @@ Required:
 Optional:
 
 - `report_workflow_status` (String) Report the workflow status when invoking the action
-- `workflow_inputs` (String) The GitHub workflow inputs (key-value object encoded to a string)
+- `workflow_inputs` (String) The GitHub [workflow inputs](https://docs.getport.io/create-self-service-experiences/setup-backend/#define-the-actions-payload) should be in `JSON` format, encoded as a string. Use [jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode) to encode arrays or objects. Learn about how to [define the action payload](https://docs.getport.io/create-self-service-experiences/setup-backend/#define-the-actions-payload).
 
 
 <a id="nestedatt--gitlab_method"></a>
@@ -252,7 +252,7 @@ Required:
 Optional:
 
 - `default_ref` (String) The default ref of the action
-- `pipeline_variables` (String) The Gitlab pipeline variables (key-value object encoded to a string)
+- `pipeline_variables` (String) The Gitlab pipeline variables should be in `JSON` format, encoded as a string. Use [jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode) to encode arrays or objects. Learn about how to [define the action payload](https://docs.getport.io/create-self-service-experiences/setup-backend/#define-the-actions-payload).
 
 
 <a id="nestedatt--kafka_method"></a>
@@ -260,7 +260,7 @@ Optional:
 
 Optional:
 
-- `payload` (String) The Kafka message payload (array or object encoded to a string)
+- `payload` (String) The Kafka message [payload](https://docs.getport.io/create-self-service-experiences/setup-backend/#define-the-actions-payload) should be in `JSON` format, encoded as a string. Use [jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode) to encode arrays or objects. Learn about how to [define the action payload](https://docs.getport.io/create-self-service-experiences/setup-backend/#define-the-actions-payload).
 
 
 <a id="nestedatt--self_service_trigger"></a>
@@ -469,9 +469,7 @@ Required:
 Optional:
 
 - `agent` (String) Use the agent to invoke the action
-- `body` (String) The Webhook body (array or object encoded to a string)
-- `headers` (Map of String) The HTTP method to invoke the action
+- `body` (String) The Webhook body should be in `JSON` format, encoded as a string. Use [jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode) to encode arrays or objects. Learn about how to [define the action payload](https://docs.getport.io/create-self-service-experiences/setup-backend/#define-the-actions-payload).
+- `headers` (Map of String) The HTTP headers for invoking the action. They should be encoded as a key-value object to a string using [jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode). Learn about how to [define the action payload](https://docs.getport.io/create-self-service-experiences/setup-backend/#define-the-actions-payload).
 - `method` (String) The HTTP method to invoke the action
 - `synchronized` (String) Synchronize the action
-
-
diff --git a/docs/resources/port_action_permissions.md b/docs/resources/port_action_permissions.md
index 9b500155..fa3bf70a 100644
--- a/docs/resources/port_action_permissions.md
+++ b/docs/resources/port_action_permissions.md
@@ -218,5 +218,3 @@ Optional:
 - `roles` (List of String) The roles with execution permission
 - `teams` (List of String) The teams with execution permission
 - `users` (List of String) The users with execution permission
-
-
diff --git a/docs/resources/port_aggregation_properties.md b/docs/resources/port_aggregation_properties.md
index 35175153..9e7bb42c 100644
--- a/docs/resources/port_aggregation_properties.md
+++ b/docs/resources/port_aggregation_properties.md
@@ -645,5 +645,3 @@ Optional:
 
 - `average_of` (String) The time periods to calculate the average of, e.g. hour, day, week, month
 - `measure_time_by` (String) The property name on which to calculate the the time periods, e.g. $createdAt, $updated_at or any other date property
-
-
diff --git a/docs/resources/port_blueprint.md b/docs/resources/port_blueprint.md
index e5b76d2d..13f0431e 100644
--- a/docs/resources/port_blueprint.md
+++ b/docs/resources/port_blueprint.md
@@ -498,5 +498,3 @@ Required:
 Optional:
 
 - `agent` (Boolean) The agent of the webhook changelog destination
-
-
diff --git a/docs/resources/port_blueprint_permissions.md b/docs/resources/port_blueprint_permissions.md
index 34a5442f..802ab5ec 100644
--- a/docs/resources/port_blueprint_permissions.md
+++ b/docs/resources/port_blueprint_permissions.md
@@ -7,63 +7,64 @@ description: |-
   Docs about blueprint permissions can be found here https://docs.getport.io/build-your-software-catalog/set-catalog-rbac/examples/#setting-blueprint-permissions
   Example Usage
   Allow access to all members:
-  hcl
-  resource "port_blueprint_permissions" "microservices_permissions" {
-    blueprint_identifier = "my_blueprint_identifier"
-    entities= {
+  ```hcl
+  resource "portblueprintpermissions" "microservicespermissions" {
+    blueprintidentifier = "myblueprintidentifier"
+    entities             = {
       "register" = {
-          "roles": [
-              "Member",
-          ],
-          "users": [],
-          "teams": []
+        "roles" : [
+          "Member",
+        ],
+        "users" : [],
+        "teams" : []
       },
       "unregister" = {
-          "roles": [
-              "Member",
-          ],
-          "users": [],
-          "teams": []
+        "roles" : [
+          "Member",
+        ],
+        "users" : [],
+        "teams" : []
       },
       "update" = {
-          "roles": [
-              "Member",
-          ],
-          "users": ["test-admin-user@test.com"],
-          "teams": []
-      },
-      "update_metadata_properties" = {
-          "icon" = {
-              "roles": [
-                  "Member",
-              ],
-              "users": [],
-              "teams": []
-          },
-          "identifier" = {
-              "roles": [
-                  "Member",
-              ],
-              "users": [],
-              "teams": ["Team Spiderman"]
-          },
-          "team" = {
-              "roles": [
-                  "Admin",
-              ],
-              "users": [],
-              "teams": []
-          },
-          "title" = {
-              "roles": [
-                  "Member",
-              ],
-              "users": [],
-              "teams": []
-          },
+        "roles" : [
+          "Member",
+        ],
+        "users" : ["test-admin-user@test.com"],
+        "teams" : []
       },
+      "updatemetadataproperties" = {
+        "icon" = {
+          "roles" : [
+            "Member",
+          ],
+          "users" : [],
+          "teams" : []
+        },
+        "identifier" = {
+          "roles" : [
+            "Member",
+          ],
+          "users" : [],
+          "teams" : ["Team Spiderman"]
+        },
+        "team" = {
+          "roles" : [
+            "Admin",
+          ],
+          "users" : [],
+          "teams" : []
+        },
+        "title" = {
+          "roles" : [
+            "Member",
+          ],
+          "users" : [],
+          "teams" : []
+        }
+      }
+    }
   }
-  
+  ```
   NOTE:
   You always need to explicity set register|unregister|update|update_metadata_propertiesproperties
   Allow update myStringProperty` for admins and a specific user and team:
@@ -120,59 +121,61 @@ Docs about blueprint permissions can be found [here](https://docs.getport.io/bui
 ```hcl
 resource "port_blueprint_permissions" "microservices_permissions" {
   blueprint_identifier = "my_blueprint_identifier"
-  entities= {
-	"register" = {
-		"roles": [
-			"Member",
-		],
-		"users": [],
-		"teams": []
-	},
-	"unregister" = {
-		"roles": [
-			"Member",
-		],
-		"users": [],
-		"teams": []
-	},
-	"update" = {
-		"roles": [
-			"Member",
-		],
-		"users": ["test-admin-user@test.com"],
-		"teams": []
-	},
-	"update_metadata_properties" = {
-		"icon" = {
-			"roles": [
-				"Member",
-			],
-			"users": [],
-			"teams": []
-		},
-		"identifier" = {
-			"roles": [
-				"Member",
-			],
-			"users": [],
-			"teams": ["Team Spiderman"]
-		},
-		"team" = {
-			"roles": [
-				"Admin",
-			],
-			"users": [],
-			"teams": []
-		},
-		"title" = {
-			"roles": [
-				"Member",
-			],
-			"users": [],
-			"teams": []
-		},
-	},
+  entities             = {
+    "register" = {
+      "roles" : [
+        "Member",
+      ],
+      "users" : [],
+      "teams" : []
+    },
+    "unregister" = {
+      "roles" : [
+        "Member",
+      ],
+      "users" : [],
+      "teams" : []
+    },
+    "update" = {
+      "roles" : [
+        "Member",
+      ],
+      "users" : ["test-admin-user@test.com"],
+      "teams" : []
+    },
+    "update_metadata_properties" = {
+      "icon" = {
+        "roles" : [
+          "Member",
+        ],
+        "users" : [],
+        "teams" : []
+      },
+      "identifier" = {
+        "roles" : [
+          "Member",
+        ],
+        "users" : [],
+        "teams" : ["Team Spiderman"]
+      },
+      "team" = {
+        "roles" : [
+          "Admin",
+        ],
+        "users" : [],
+        "teams" : []
+      },
+      "title" = {
+        "roles" : [
+          "Member",
+        ],
+        "users" : [],
+        "teams" : []
+      }
+    }
+  }
 }
+
 ```
 
 #### NOTE:
@@ -244,17 +247,17 @@ resource "port_blueprint_permissions" "microservices_permissions" {
 
 Required:
 
-- `register` (Attributes) Enable permissions to register entities of the blueprint (see [below for nested schema](#nestedatt--entities--register))
-- `unregister` (Attributes) Enable permissions to unregister entities of the blueprint (see [below for nested schema](#nestedatt--entities--unregister))
-- `update` (Attributes) Enable permissions to update entities of the blueprint (see [below for nested schema](#nestedatt--entities--update))
+- `register` (Attributes) Manage permissions to register entities of the blueprint (see [below for nested schema](#nestedatt--entities--register))
+- `unregister` (Attributes) Manage permissions to unregister entities of the blueprint (see [below for nested schema](#nestedatt--entities--unregister))
+- `update` (Attributes) Manage permissions to update entities of the blueprint (see [below for nested schema](#nestedatt--entities--update))
 - `update_metadata_properties` (Attributes) Manage permissions to the metadata properties (`$icon|$title|$team|$identifier`)
 These are translated to the updateProperties in the Port Api, proxied since we can't have Terraform properties starting with `$`signs.
 See [here](https://docs.getport.io/build-your-software-catalog/customize-integrations/configure-data-model/setup-blueprint/properties/meta-properties/) for more details. (see [below for nested schema](#nestedatt--entities--update_metadata_properties))
 
 Optional:
 
-- `update_properties` (Attributes Map) Enable permissions to update the entity properties (see [below for nested schema](#nestedatt--entities--update_properties))
-- `update_relations` (Attributes Map) Enable permissions to update the entity relations (see [below for nested schema](#nestedatt--entities--update_relations))
+- `update_properties` (Attributes Map) Manage permissions to update the entity properties (see [below for nested schema](#nestedatt--entities--update_properties))
+- `update_relations` (Attributes Map) Manage permissions to update the entity relations (see [below for nested schema](#nestedatt--entities--update_relations))
 
 <a id="nestedatt--entities--register"></a>
 ### Nested Schema for `entities.register`
diff --git a/docs/resources/port_entity.md b/docs/resources/port_entity.md
index a5524c46..5c1535ea 100644
--- a/docs/resources/port_entity.md
+++ b/docs/resources/port_entity.md
@@ -67,5 +67,3 @@ Optional:
 
 - `many_relations` (Map of List of String) The many relation of the entity
 - `single_relations` (Map of String) The single relation of the entity
-
-
diff --git a/docs/resources/port_page_permissions.md b/docs/resources/port_page_permissions.md
index 394ee512..68a62550 100644
--- a/docs/resources/port_page_permissions.md
+++ b/docs/resources/port_page_permissions.md
@@ -121,5 +121,3 @@ Optional:
 - `roles` (List of String) The roles with read permission
 - `teams` (List of String) The teams with read permission
 - `users` (List of String) The users with read permission
-
-
diff --git a/docs/resources/port_scorecard.md b/docs/resources/port_scorecard.md
index dd78c955..bc13c874 100644
--- a/docs/resources/port_scorecard.md
+++ b/docs/resources/port_scorecard.md
@@ -243,5 +243,3 @@ Required:
 
 - `combinator` (String) The combinator of the query
 - `conditions` (List of String) The conditions of the query. Each condition object should be encoded to a string
-
-
diff --git a/docs/resources/port_team.md b/docs/resources/port_team.md
index 59f9484b..518df378 100644
--- a/docs/resources/port_team.md
+++ b/docs/resources/port_team.md
@@ -30,5 +30,3 @@ Team resource
 - `id` (String) The ID of this resource.
 - `provider_name` (String) The provider of the team
 - `updated_at` (String) The last update date of the team
-
-
diff --git a/docs/resources/port_webhook.md b/docs/resources/port_webhook.md
index 0e5c06ca..89654c52 100644
--- a/docs/resources/port_webhook.md
+++ b/docs/resources/port_webhook.md
@@ -75,5 +75,3 @@ Optional:
 - `signature_algorithm` (String) The signature algorithm of the webhook
 - `signature_header_name` (String) The signature header name of the webhook
 - `signature_prefix` (String) The signature prefix of the webhook
-
-
diff --git a/port/action/schema.go b/port/action/schema.go
index a1eec1ca..4adf4d9e 100644
--- a/port/action/schema.go
+++ b/port/action/schema.go
@@ -138,7 +138,7 @@ func ActionSchema() map[string]schema.Attribute {
 			Optional:            true,
 			Attributes: map[string]schema.Attribute{
 				"payload": schema.StringAttribute{
-					MarkdownDescription: "The Kafka message payload (array or object encoded to a string)",
+					MarkdownDescription: "The Kafka message [payload](https://docs.getport.io/create-self-service-experiences/setup-backend/#define-the-actions-payload) should be in `JSON` format, encoded as a string. Use [jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode) to encode arrays or objects. Learn about how to [define the action payload](https://docs.getport.io/create-self-service-experiences/setup-backend/#define-the-actions-payload).",
 					Optional:            true,
 				},
 			},
@@ -175,12 +175,12 @@ func ActionSchema() map[string]schema.Attribute {
 					Optional:            true,
 				},
 				"headers": schema.MapAttribute{
-					MarkdownDescription: "The HTTP method to invoke the action",
+					MarkdownDescription: "The HTTP headers for invoking the action. They should be encoded as a key-value object to a string using [jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode). Learn about how to [define the action payload](https://docs.getport.io/create-self-service-experiences/setup-backend/#define-the-actions-payload).",
 					ElementType:         types.StringType,
 					Optional:            true,
 				},
 				"body": schema.StringAttribute{
-					MarkdownDescription: "The Webhook body (array or object encoded to a string)",
+					MarkdownDescription: "The Webhook body should be in `JSON` format, encoded as a string. Use [jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode) to encode arrays or objects. Learn about how to [define the action payload](https://docs.getport.io/create-self-service-experiences/setup-backend/#define-the-actions-payload).",
 					Optional:            true,
 				},
 			},
@@ -202,7 +202,7 @@ func ActionSchema() map[string]schema.Attribute {
 					Required:            true,
 				},
 				"workflow_inputs": schema.StringAttribute{
-					MarkdownDescription: "The GitHub workflow inputs (key-value object encoded to a string)",
+					MarkdownDescription: "The GitHub [workflow inputs](https://docs.getport.io/create-self-service-experiences/setup-backend/#define-the-actions-payload) should be in `JSON` format, encoded as a string. Use [jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode) to encode arrays or objects. Learn about how to [define the action payload](https://docs.getport.io/create-self-service-experiences/setup-backend/#define-the-actions-payload).",
 					Optional:            true,
 				},
 				"report_workflow_status": schema.StringAttribute{
@@ -229,7 +229,7 @@ func ActionSchema() map[string]schema.Attribute {
 					Optional:            true,
 				},
 				"pipeline_variables": schema.StringAttribute{
-					MarkdownDescription: "The Gitlab pipeline variables (key-value object encoded to a string)",
+					MarkdownDescription: "The Gitlab pipeline variables should be in `JSON` format, encoded as a string. Use [jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode) to encode arrays or objects. Learn about how to [define the action payload](https://docs.getport.io/create-self-service-experiences/setup-backend/#define-the-actions-payload).",
 					Optional:            true,
 				},
 			},
@@ -247,7 +247,7 @@ func ActionSchema() map[string]schema.Attribute {
 					Required:            true,
 				},
 				"payload": schema.StringAttribute{
-					MarkdownDescription: "The Azure Devops workflow payload (array or object encoded to a string)",
+					MarkdownDescription: "The Azure Devops workflow [payload](https://docs.getport.io/create-self-service-experiences/setup-backend/#define-the-actions-payload) should be in `JSON` format, encoded as a string. Use [jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode) to encode arrays or objects. Learn about how to [define the action payload](https://docs.getport.io/create-self-service-experiences/setup-backend/#define-the-actions-payload).",
 					Optional:            true,
 				},
 			},
diff --git a/port/blueprint-permissions/schema.go b/port/blueprint-permissions/schema.go
index 6e3af549..471a8c15 100644
--- a/port/blueprint-permissions/schema.go
+++ b/port/blueprint-permissions/schema.go
@@ -55,18 +55,18 @@ func BlueprintPermissionsSchema() map[string]schema.Attribute {
 			Attributes: map[string]schema.Attribute{
 				"register": schema.SingleNestedAttribute{
 					MarkdownDescription: "Manage permissions to register entities of the blueprint",
-					Required:   true,
-					Attributes: getAssigneeProps("register"),
+					Required:            true,
+					Attributes:          getAssigneeProps("register"),
 				},
 				"unregister": schema.SingleNestedAttribute{
 					MarkdownDescription: "Manage permissions to unregister entities of the blueprint",
-					Required:   true,
-					Attributes: getAssigneeProps("unregister"),
+					Required:            true,
+					Attributes:          getAssigneeProps("unregister"),
 				},
 				"update": schema.SingleNestedAttribute{
 					MarkdownDescription: "Manage permissions to update entities of the blueprint",
-					Required:   true,
-					Attributes: getAssigneeProps("update"),
+					Required:            true,
+					Attributes:          getAssigneeProps("update"),
 				},
 				"update_metadata_properties": schema.SingleNestedAttribute{
 					Required: true,
@@ -76,29 +76,29 @@ See [here](https://docs.getport.io/build-your-software-catalog/customize-integra
 					Attributes: map[string]schema.Attribute{
 						"icon": schema.SingleNestedAttribute{
 							MarkdownDescription: "The entity's icon",
-							Required:   true,
-							Attributes: getAssigneeProps("update $icon metadata"),
+							Required:            true,
+							Attributes:          getAssigneeProps("update $icon metadata"),
 						},
 						"title": schema.SingleNestedAttribute{
 							MarkdownDescription: "A human-readable name for the entity",
-							Required:   true,
-							Attributes: getAssigneeProps("update $title metadata"),
+							Required:            true,
+							Attributes:          getAssigneeProps("update $title metadata"),
 						},
 						"team": schema.SingleNestedAttribute{
 							MarkdownDescription: "The team this entity belongs to",
-							Required:   true,
-							Attributes: getAssigneeProps("update $team metadata"),
+							Required:            true,
+							Attributes:          getAssigneeProps("update $team metadata"),
 						},
 						"identifier": schema.SingleNestedAttribute{
 							MarkdownDescription: "Unique Entity identifier, used for API calls, programmatic access and distinguishing between different entities",
-							Required:   true,
-							Attributes: getAssigneeProps("update $identifier metadata"),
+							Required:            true,
+							Attributes:          getAssigneeProps("update $identifier metadata"),
 						},
 					},
 				},
 				"update_properties": schema.MapNestedAttribute{
 					MarkdownDescription: "Manage permissions to update the entity properties",
-					Optional: true,
+					Optional:            true,
 					NestedObject: schema.NestedAttributeObject{
 						Attributes: getAssigneeProps("update specific property"),
 					},
@@ -113,7 +113,7 @@ See [here](https://docs.getport.io/build-your-software-catalog/customize-integra
 				},
 				"update_relations": schema.MapNestedAttribute{
 					MarkdownDescription: "Manage permissions to update the entity relations",
-					Optional: true,
+					Optional:            true,
 					NestedObject: schema.NestedAttributeObject{
 						Attributes: getAssigneeProps("update specific relation"),
 					},
@@ -143,59 +143,61 @@ Docs about blueprint permissions can be found [here](https://docs.getport.io/bui
 ` + "```hcl" + `
 resource "port_blueprint_permissions" "microservices_permissions" {
   blueprint_identifier = "my_blueprint_identifier"
-  entities= {
-	"register" = {
-		"roles": [
-			"Member",
-		],
-		"users": [],
-		"teams": []
-	},
-	"unregister" = {
-		"roles": [
-			"Member",
-		],
-		"users": [],
-		"teams": []
-	},
-	"update" = {
-		"roles": [
-			"Member",
-		],
-		"users": ["test-admin-user@test.com"],
-		"teams": []
-	},
-	"update_metadata_properties" = {
-		"icon" = {
-			"roles": [
-				"Member",
-			],
-			"users": [],
-			"teams": []
-		},
-		"identifier" = {
-			"roles": [
-				"Member",
-			],
-			"users": [],
-			"teams": ["Team Spiderman"]
-		},
-		"team" = {
-			"roles": [
-				"Admin",
-			],
-			"users": [],
-			"teams": []
-		},
-		"title" = {
-			"roles": [
-				"Member",
-			],
-			"users": [],
-			"teams": []
-		},
-	},
-}` + "\n```" + `
+  entities             = {
+    "register" = {
+      "roles" : [
+        "Member",
+      ],
+      "users" : [],
+      "teams" : []
+    },
+    "unregister" = {
+      "roles" : [
+        "Member",
+      ],
+      "users" : [],
+      "teams" : []
+    },
+    "update" = {
+      "roles" : [
+        "Member",
+      ],
+      "users" : ["test-admin-user@test.com"],
+      "teams" : []
+    },
+    "update_metadata_properties" = {
+      "icon" = {
+        "roles" : [
+          "Member",
+        ],
+        "users" : [],
+        "teams" : []
+      },
+      "identifier" = {
+        "roles" : [
+          "Member",
+        ],
+        "users" : [],
+        "teams" : ["Team Spiderman"]
+      },
+      "team" = {
+        "roles" : [
+          "Admin",
+        ],
+        "users" : [],
+        "teams" : []
+      },
+      "title" = {
+        "roles" : [
+          "Member",
+        ],
+        "users" : [],
+        "teams" : []
+      }
+    }
+  }
+}
+` + "\n```" + `
 
 #### NOTE: