docs(terraform): Updated the documentation.

Author: skyzyx

corefunc/truncate_label.go

@@ -10,6 +10,10 @@ TruncateLabel supports prepending a prefix to a label, while truncating them
 to meet the maximum length constraints. Useful when grouping labels with a
 kind of prefix. Both the prefix and the label will be truncated if necessary.
 
+Uses a "balancing" algorithm between the prefix and the label, so that each
+section is truncated as a factor of how much space it takes up in the merged
+string.
+
 ----
 
 * maxLength (int64): The maximum allowed length of the combined label.

corefunc/truncate_label_data_source.go

@@ -75,7 +75,18 @@ func (d *truncateLabelDataSource) Schema(
         TruncateLabel supports prepending a prefix to a label, while truncating them
         to meet the maximum length constraints. Useful when grouping labels with a
         kind of prefix. Both the prefix and the label will be truncated if necessary.
-		`)),
+
+        Uses a "balancing" algorithm between the prefix and the label, so that each
+        section is truncated as a factor of how much space it takes up in the merged
+        string.
+
+        -> The motivation for this is in working with monitoring systems such
+        as New Relic and Datadog where there are hundreds of applications in a
+        monitoring "prod" account, and also hundreds of applications in a monitoring
+        "nonprod" account. This allows us to group lists of monitors together using a
+        shared prefix, but also truncate them appropriately to fit length
+        constraints for names.
+        `)),
 		Attributes: map[string]schema.Attribute{
 			"id": schema.Int64Attribute{
 				Description: "Not used. Required by the " +

docs/data-sources/truncate_label.md docs/data-sources/str_truncate_label.md

@@ -6,6 +6,15 @@ description: |-
   TruncateLabel supports prepending a prefix to a label, while truncating them
   to meet the maximum length constraints. Useful when grouping labels with a
   kind of prefix. Both the prefix and the label will be truncated if necessary.
+  Uses a "balancing" algorithm between the prefix and the label, so that each
+  section is truncated as a factor of how much space it takes up in the merged
+  string.
+  -> The motivation for this is in working with monitoring systems such
+  as New Relic and Datadog where there are hundreds of applications in a
+  monitoring "prod" account, and also hundreds of applications in a monitoring
+  "nonprod" account. This allows us to group lists of monitors together using a
+  shared prefix, but also truncate them appropriately to fit length
+  constraints for names.
 ---
 -->
 
@@ -15,6 +24,17 @@ TruncateLabel supports prepending a prefix to a label, while truncating them
 to meet the maximum length constraints. Useful when grouping labels with a
 kind of prefix. Both the prefix and the label will be truncated if necessary.
 
+Uses a "balancing" algorithm between the prefix and the label, so that each
+section is truncated as a factor of how much space it takes up in the merged
+string.
+
+-> The motivation for this is in working with monitoring systems such
+as New Relic and Datadog where there are hundreds of applications in a
+monitoring "prod" account, and also hundreds of applications in a monitoring
+"nonprod" account. This allows us to group lists of monitors together using a
+shared prefix, but also truncate them appropriately to fit length
+constraints for names.
+
 ## Example Usage
 
 ```terraform