From 9ebcc9491863dba8b9d3c61f7bb9a47d1780583c Mon Sep 17 00:00:00 2001
From: pranav-new-relic <pnandula@newrelic.com>
Date: Wed, 5 Jun 2024 12:46:24 +0530
Subject: [PATCH] docs(entity): update verbiage

---
 website/docs/d/entity.html.markdown | 61 +++++++++++++++--------------
 1 file changed, 32 insertions(+), 29 deletions(-)

diff --git a/website/docs/d/entity.html.markdown b/website/docs/d/entity.html.markdown
index 72446018a..84b92c8b8 100644
--- a/website/docs/d/entity.html.markdown
+++ b/website/docs/d/entity.html.markdown
@@ -165,16 +165,42 @@ In addition to all arguments above, the following attributes are exported:
 * `guid` - The unique GUID of the entity.
 * `application_id` - The domain-specific application ID of the entity. Only returned for APM and Browser applications.
 * `serving_apm_application_id` - The browser-specific ID of the backing APM entity. Only returned for Browser applications.
-* `entity_tags` - The `entity_tags` helps retrieve tags associated with the entity fetched by the data source, the tags are returned as a JSON-encoded string and not a conventional list or a map, owing to a couple of design considerations; which is why one would need to use the Terraform function `jsondecode()`, along with the attribute entity_tags in order to convert the JSON-encoded string into a map with key-value pairs.
-
+* `entity_tags` - A JSON-encoded string, comprising tags associated with the entity fetched.
+    * See the [**Additional Examples**](#using-the-entity_tags-attribute-to-fetch-tags-associated-with-the-entity) section below, for an illustration depicting the usage of `jsondecode` with the attribute `entity_tags`, to get the tags associated with the entity fetched.
 
 ## Additional Examples
 
 -> If the entities are not found please try again without providing the `type` field.
 
-### Entity Tags
+### Query for an OTEL entity
+
+```hcl
+data "newrelic_entity" "app" {
+  name = "my-otel-app"
+  domain = "EXT"
+  type = "SERVICE"
+
+  tag {
+    key = "accountID"
+    value = "12345"
+  }
+}
+```
+
+### Query for an entity by type (AWS Lambda entity in this example)
+
+```hcl
+data "newrelic_entity" "app" {
+  name = "my_lambda_trace"
+  type = "AWSLAMBDAFUNCTION"
+}
+```
+
+### Using the `entity_tags` Attribute to Fetch Tags Associated with the Entity
+
+As stated above in the [**Attributes Reference**](#attributes-reference) section, while the attribute `entity_tags` helps retrieve tags associated with the entity fetched by the data source, the tags are returned as a JSON-encoded string and not a conventional list or a map, owing to a couple of design considerations; which is why one would need to use the Terraform function `jsondecode()`, along with the attribute `entity_tags` in order to convert the JSON-encoded string into a map with key-value pairs.
 
-* The following is an illustration of the aforementioned scenario. It may be observed that a key-value pair version of the JSON-encoded string exported by `entity_tags` is written to the variable `key_value_maps` , using the `jsondecode()` function.
+The following is an illustration of the aforementioned scenario. It may be observed that a key-value pair version of the JSON-encoded string exported by `entity_tags` is written to the variable `key_value_maps` , using the `jsondecode()` function.
 
 ```hcl
 data "newrelic_entity" "foo" {
@@ -190,9 +216,9 @@ locals {
 output "key_value_map" {
   value = local.key_value_map
 }
-```
-The value of `local.key_value_map` would look like the following.
 
+```
+The value of `local.key_value_map`  would look like the following.
 ```hcl
 {
   env = ["production"]
@@ -208,26 +234,3 @@ locals {
 }
 ```
 
-### Query for an OTEL entity
-
-```hcl
-data "newrelic_entity" "app" {
-  name = "my-otel-app"
-  domain = "EXT"
-  type = "SERVICE"
-
-  tag {
-    key = "accountID"
-    value = "12345"
-  }
-}
-```
-
-### Query for an entity by type (AWS Lambda entity in this example)
-
-```hcl
-data "newrelic_entity" "app" {
-  name = "my_lambda_trace"
-  type = "AWSLAMBDAFUNCTION"
-}
-```