Note: Doc team updates the current version of the documentation and the
two previous versions (n-2), but we address *only high-priority, or
customer-reported issues* for -2 releases in support.
Describe the changes in the doc and link to your dev story:

1. - [ ] Mandatory: Add the required version to the Fix version/s field.

2. - [x] Mandatory: Choose the type of documentation change or review.

• [x] We need to update to an existing topic

• [ ] We need to add a new document to an existing section

• [ ] We need a whole new section; this is a function not
  documented before and doesn't belong in any current section

• [ ] We need an Operator Advisory review and approval

• [ ] We need a z-Stream (Errata) Advisory and Release note
  for MCE and/or ACM

3. - [x] *Mandatory: *Use the following link to open the doc and find where the
documentation update should go. Note: As the feature and doc is
understood and developed, this placement decision may change:

• Published doc: https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.11/html-single/governance/index#configuration-policy-yaml-table 
• Source: https://github.com/stolostron/rhacm-docs/blob/2.12_stage/governance/config_policy_ctrl.adoc 

4. - [x] Mandatory for GA content:

• [x] Add steps, the diff, known issue, and/or other important
  conceptual information in the following space:

We now allow the user to customize the message emitted by the ConfigurationPolicy and displayed on the hub. For example, a policy for a namespace would previously always emit a message like "violation - namespaces [test-case-41] not found", but now the policy author can specify a message for when the policy is compliant, and when it is noncompliant. They can then see something fun like "Good news: the namespace test-case-41 is great" when it is compliant, and something with more information about how to remediate it when it is noncompliant, like "Uh-oh, something is wrong with namespace test-case-41, contact the admin in slack channel #example".

The new field is at `.spec. customMessage`, with subfields for `.compliant` and `.noncompliant`, similar to how the evaluationInterval works. Each field can use go templating, (double curly brackets, like we support in other "templated" fields like object-templates-raw), but I'm wondering if we should avoid the word 'template' because it is so overloaded already in Policy... I'm looking for suggestions for a better term here.

The fields support any UTF-8 encoded characters, including emoji and foreign characters.

The fields have two top-level objects available to the Go templating engine, `.DefaultMessage` which contains the message that would be emitted if there was no customization, and `.Policy` which contains the full current state of the ConfigurationPolicy, including its status. In addition, each `.Policy.status.relatedObjects[*].object` will have the full state of those objects, as opposed to just the identifier information that is actually stored in the policy status. So for example, a user can access `.Policy.status.relatedObject[0].object.status.phase` in a policy for a namespace, and see whether the namespace is Active or Terminating, or some other state, and include that in the message, even though that information is not visible in the ConfigurationPolicy normally.

• [ ] *Add Required access level *(example, *Cluster
  Administrator*) for the user to complete the task:

• [ ] Add verification at the end of the task, how does the user
  verify success (a command to run or a result to see?)

• [x] Add link to dev story here: https://issues.redhat.com/browse/ACM-12423

5. - [x] Mandatory for bugs: What is the diff? Clearly define what the
problem is, what the change is, and link to the current documentation. Only
use this for a documentation bug.

I think this would need new entries in the ConfigurationPolicy table at https://github.com/stolostron/rhacm-docs/blob/2.12_stage/governance/config_policy_ctrl.adoc#configuration-policy-yaml-table, for `spec.customMessage.compliant` and `spec.customMessage.noncompliant`.

The current API description may provide a decent draft (and should also probably be reviewed):

• CustomMessage configures the compliance messages emitted by the configuration policy, to use one of the specified Go templates based on the current compliance. The data passed to the templates include a `.DefaultMessage` string variable which matches the message that would be emitted if no custom template was defined, and a `.Policy` object variable which contains the full current state of the policy. If the policy is using Kubernetes API watches (default but can be configured with EvaluationInterval), and the object exists, then the full state of each related object will be available at `.Policy.status.relatedObjects[*].object`. Otherwise, only the identifier information will be available there.

This feature might also deserve a call-out in a What's New section for 2.12.

If it would fit into the docs, we (dev) can provide some examples demonstrating the capabilities of the customization.