Merge pull request #214610 from shanhix1/patch-13

Clarify best practices for attestations

Author: prmerger-automator[bot]

articles/governance/policy/concepts/attestation-structure.md

@@ -11,14 +11,23 @@ author: timwarner-msft
 Attestations are used by Azure Policy to set compliance states of resources or scopes targeted by [manual policies](effects.md#manual-preview). They also allow users to provide additional metadata or link to evidence which accompanies the attested compliance state.  
 
 > [!NOTE]
-> In preview, Attestations are available only through the Azure Resource Manager (ARM) API.
+> In preview, Attestations are available only through the [Azure Resource Manager (ARM) API](/rest/api/policy/attestations).
 
-Below is an example of creating a new attestation resource which sets the compliance state for resources within a desired resource group:
+## Best practices
+
+Attestations can be used to set the compliance state of an individual resource for a given manual policy. This means that each applicable resource requires one attestation per manual policy assignment. For ease of management, manual policies should be designed to target the scope which defines the boundary of resources whose compliance state needs to be attested. 
+
+For example, suppose an organization divides teams by resource group, and each team is required to attest to development of procedures for handling resources within that resource group. In this scenario, the conditions of the policy rule should specify that type equals `Microsoft.Resources/resourceGroups`. This way, one attestation is required for the resource group, rather than for each individual resource within. Similarly, if the organization deivides teams by subscriptions, the policy rule should target `Microsoft.Resources/subscriptions`.  
+
+Typically, the provided evidence should correspond with relevant scopes of the organizational structure. This pattern prevents the need to duplicate evidence across many attestations. Such duplications would make manual policies difficult to manage, and indicate that the policy definition targets the wrong resource(s).
+
+## Example attestation
+
+Below is an example of creating a new attestation resource which sets the compliance state for a resource group targeted by a manual policy assignment:
 
 ```http
 PUT http://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.PolicyInsights/attestations/{name}?api-version=2019-10-01
 ```
-Attestations can be used to set the compliance state of an individual resource or a scope. A resource can have one attestation for an individual manual policy assignment.
 
 ## Request body
 

articles/governance/policy/concepts/effects.md

@@ -747,10 +747,7 @@ Example: Gatekeeper v2 admission control rule to allow only the specified contai
 
 ## Manual (preview)
 
-The new `manual` (preview) effect enables you to define and track your own custom attestation
-resources. Unlike other Policy definitions that actively scan for evaluation, the Manual effect
-allows for manual changes to the compliance state. To change the compliance for a manual policy,
-you'll need to create an attestation for that compliance state.
+The new `manual` (preview) effect enables you to self-attest the compliance of resources or scopes. Unlike other policy definitions that actively scan for evaluation, the Manual effect allows for manual changes to the compliance state. To change the compliance of a resource or scope targeted by a manual policy, you'll need to create an [attestation](attestation-structure.md). The [best practice](attestation-structure.md#best-practices) is to design manual policies that target the scope which defines the boundary of resources whose compliance need attesting.
 
 > [!NOTE]
 > During Public Preview, support for manual policy is available through various Microsoft Defender