[Doc] Clarify difference between databricks_grants resources (#4906)

## Changes
- Clarify difference between `databricks_grants` resources

## Tests
<!--
How is this tested? Please see the checklist below and also describe any
other relevant tests
-->

- [x] relevant change in `docs/` folder

Author: nkvuong

NEXT_CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Release v1.86.0
 
 ### Breaking Changes
+
 * Do not set `run_as from run_as_user_name in DLT pipelines. This fixes an issue where the value for run_as was unintentionally cached in the terraform state. More details and the workaround are specified in the PR: ([#4886](https://github.com/databricks/terraform-provider-databricks/pull/4886))
 
 ### New Features and Improvements
@@ -33,6 +34,7 @@
 * Improve docs for `databricks_compliance_security_profile_setting` ([#4880](https://github.com/databricks/terraform-provider-databricks/pull/4880)).
 * Improve instructions for the Terraform Exporter ([#4892](https://github.com/databricks/terraform-provider-databricks/pull/4892)).
 * Improve documentation for service principal data sources ([#4900](https://github.com/databricks/terraform-provider-databricks/pull/4900)).
+* Improve documentation for grants resources ([#4906](https://github.com/databricks/terraform-provider-databricks/pull/4906))
 
 ### Exporter
 

docs/resources/grant.md

@@ -7,6 +7,8 @@ subcategory: "Unity Catalog"
 
 -> Most of Unity Catalog APIs are only accessible via **workspace-level APIs**. This design may change in the future. Account-level principal grants can be assigned with any valid workspace as the Unity Catalog is decoupled from specific workspaces. More information in [the official documentation](https://docs.databricks.com/data-governance/unity-catalog/index.html).
 
+~> This resource is _authoritative_ for grants on securables for a given principal. Configuring this resource for a securable will **OVERWRITE** any existing grants for the principal and changes made outside of Terraform will be reset.
+
 In Unity Catalog all users initially have no access to data. Only Metastore Admins can create objects and can grant/revoke access on individual objects to users and groups. Every securable object in Unity Catalog has an owner. The owner can be any account-level user or group, called principals in general. The principal that creates an object becomes its owner. Owners receive `ALL_PRIVILEGES` on the securable object (e.g., `SELECT` and `MODIFY` on a table), as well as the permission to grant privileges to other principals.
 
 Securable objects are hierarchical and privileges are inherited downward. The highest level object that privileges are inherited from is the catalog. This means that granting a privilege on a catalog or schema automatically grants the privilege to all current and future objects within the catalog or schema. Privileges that are granted on a metastore are not inherited.
@@ -18,7 +20,7 @@ Every `databricks_grant` resource must have exactly one securable identifier and
 
 For the latest list of privilege types that apply to each securable object in Unity Catalog, please refer to the [official documentation](https://docs.databricks.com/en/data-governance/unity-catalog/manage-privileges/privileges.html#privilege-types-by-securable-object-in-unity-catalog)
 
-Terraform will handle any configuration drift for the specified principal on every `terraform apply` run, even when grants are changed outside of Terraform state.
+Unlike the [SQL specification](https://docs.databricks.com/sql/language-manual/sql-ref-privileges.html#privilege-types), all privileges to be written with underscore instead of space, e.g. `CREATE_TABLE` and not `CREATE TABLE`.
 
 See [databricks_grants](grants.md) for the list of privilege types that apply to each securable object.
 

docs/resources/grants.md

@@ -7,10 +7,7 @@ subcategory: "Unity Catalog"
 
 -> Most of Unity Catalog APIs are only accessible via **workspace-level APIs**. This design may change in the future. Account-level principal grants can be assigned with any valid workspace as the Unity Catalog is decoupled from specific workspaces. More information in [the official documentation](https://docs.databricks.com/data-governance/unity-catalog/index.html).
 
-Two different resources help you manage your Unity Catalog grants for a securable. Each of these resources serves a different use case:
-
-- [databricks_grants](https://registry.terraform.io/providers/databricks/databricks/latest/docs/resources/grants): Authoritative. Sets the grants of a securable and *replaces* any existing grants defined inside or outside of Terraform.
-- [databricks_grant](https://registry.terraform.io/providers/databricks/databricks/latest/docs/resources/grant): Authoritative for a given principal. Updates the grants of a securable to a single principal. Other principals within the grants for the securables are preserved.
+~> This resource is _authoritative_ for grants on securables. Configuring this resource for a securable will **OVERWRITE** any existing grants and changes made outside of Terraform will be reset. Use [databricks_grant](https://registry.terraform.io/providers/databricks/databricks/latest/docs/resources/grant) for more granular grant management.
 
 In Unity Catalog all users initially have no access to data. Only Metastore Admins can create objects and can grant/revoke access on individual objects to users and groups. Every securable object in Unity Catalog has an owner. The owner can be any account-level user or group, called principals in general. The principal that creates an object becomes its owner. Owners receive `ALL_PRIVILEGES` on the securable object (e.g., `SELECT` and `MODIFY` on a table), as well as the permission to grant privileges to other principals.
 
@@ -23,8 +20,6 @@ Every `databricks_grants` resource must have exactly one securable identifier an
 
 For the latest list of privilege types that apply to each securable object in Unity Catalog, please refer to the [official documentation](https://docs.databricks.com/en/data-governance/unity-catalog/manage-privileges/privileges.html#privilege-types-by-securable-object-in-unity-catalog)
 
-Terraform will handle any configuration drift on every `terraform apply` run, even when grants are changed outside of Terraform state.
-
 When applying grants using an identity with [`MANAGE` permission](https://docs.databricks.com/aws/en/data-governance/unity-catalog/manage-privileges/ownership#ownership-versus-the-manage-privilege), their `MANAGE` permission must also be defined, otherwise Terraform will remove their permissions, leading to errors.
 
 Unlike the [SQL specification](https://docs.databricks.com/sql/language-manual/sql-ref-privileges.html#privilege-types), all privileges to be written with underscore instead of space, e.g. `CREATE_TABLE` and not `CREATE TABLE`. Below summarizes which privilege types apply to each securable object in the catalog:
@@ -79,7 +74,7 @@ resource "databricks_grants" "sandbox" {
 
 ## Schema grants
 
-You can grant `ALL_PRIVILEGES`, `APPLY_TAG`, `CREATE_FUNCTION`, `CREATE_TABLE`, `CREATE_VOLUME`, `MANAGE` and `USE_SCHEMA` privileges to [*`catalog.schema`*](schema.md) specified in the `schema` attribute. You can also grant `EXECUTE`, `MODIFY`, `REFRESH`, `SELECT`, `READ_VOLUME`, `WRITE_VOLUME` at the schema level to apply them to the pertinent current and future securable objects within the schema:
+You can grant `ALL_PRIVILEGES`, `APPLY_TAG`, `CREATE_FUNCTION`, `CREATE_TABLE`, `CREATE_VOLUME`, `MANAGE` and `USE_SCHEMA` privileges to [_`catalog.schema`_](schema.md) specified in the `schema` attribute. You can also grant `EXECUTE`, `MODIFY`, `REFRESH`, `SELECT`, `READ_VOLUME`, `WRITE_VOLUME` at the schema level to apply them to the pertinent current and future securable objects within the schema:
 
 ```hcl
 resource "databricks_schema" "things" {
@@ -102,7 +97,7 @@ resource "databricks_grants" "things" {
 
 ## Table grants
 
-You can grant `ALL_PRIVILEGES`, `APPLY_TAG`, `MANAGE`, `SELECT` and `MODIFY` privileges to [*`catalog.schema.table`*](sql_table.md) specified in the `table` attribute.
+You can grant `ALL_PRIVILEGES`, `APPLY_TAG`, `MANAGE`, `SELECT` and `MODIFY` privileges to [_`catalog.schema.table`_](sql_table.md) specified in the `table` attribute.
 
 ```hcl
 resource "databricks_grants" "customers" {
@@ -140,7 +135,7 @@ resource "databricks_grants" "things" {
 
 ## View grants
 
-You can grant `ALL_PRIVILEGES`, `APPLY_TAG`, `MANAGE` and `SELECT` privileges to [*`catalog.schema.view`*](sql_table.md) specified in `table` attribute.
+You can grant `ALL_PRIVILEGES`, `APPLY_TAG`, `MANAGE` and `SELECT` privileges to [_`catalog.schema.view`_](sql_table.md) specified in `table` attribute.
 
 ```hcl
 resource "databricks_grants" "customer360" {
@@ -174,7 +169,7 @@ resource "databricks_grants" "customers" {
 
 ## Volume grants
 
-You can grant `ALL_PRIVILEGES`, `MANAGE`, `READ_VOLUME` and `WRITE_VOLUME` privileges to [*`catalog.schema.volume`*](volume.md) specified in the `volume` attribute.
+You can grant `ALL_PRIVILEGES`, `MANAGE`, `READ_VOLUME` and `WRITE_VOLUME` privileges to [_`catalog.schema.volume`_](volume.md) specified in the `volume` attribute.
 
 ```hcl
 resource "databricks_volume" "this" {
@@ -197,7 +192,7 @@ resource "databricks_grants" "volume" {
 
 ## Registered model grants
 
-You can grant `ALL_PRIVILEGES`, `APPLY_TAG`, `EXECUTE`, and `MANAGE` privileges to [*`catalog.schema.model`*](registered_model.md) specified in the `model` attribute.
+You can grant `ALL_PRIVILEGES`, `APPLY_TAG`, `EXECUTE`, and `MANAGE` privileges to [_`catalog.schema.model`_](registered_model.md) specified in the `model` attribute.
 
 ```hcl
 resource "databricks_grants" "customers" {
@@ -215,7 +210,7 @@ resource "databricks_grants" "customers" {
 
 ## Function grants
 
-You can grant `ALL_PRIVILEGES`, `EXECUTE`, and `MANAGE` privileges to *`catalog.schema.function`* specified in the `function` attribute.
+You can grant `ALL_PRIVILEGES`, `EXECUTE`, and `MANAGE` privileges to [_`catalog.schema.function`_](../data-sources/functions.md) specified in the `function` attribute.
 
 ```hcl
 resource "databricks_grants" "udf" {