RHIDP-11225: JTBD implementation for Scorecards

assemblies/assembly-scorecards-rhdh.adoc

@@ -1,7 +1,7 @@
 :_mod-docs-content-type: ASSEMBLY
 
 [id="assembly-rhdh-observability"]
-= Understanding and visualizing {product} project health using Scorecards
+= Evaluate project health using Scorecards
 :context: assembly-scorecards-rhdh
 
 include::modules/observe/scorecards/con-understand-scorecard-plugins.adoc[leveloffset=+1]

modules/observe/scorecards/con-best-practices-for-threshold-rules.adoc

@@ -1,9 +1,9 @@
 :_mod-docs-content-type: CONCEPT
 
 [id="con-best-practices-for-threshold-rules"]
-= Verify logical flow in threshold rules
+= Verify logical flow in Scorecard threshold rules
 
-Threshold rule evaluation depends on the order of the rules. Because the system stops evaluation after a value matches the first applicable rule, you must sequence rules logically to ensure correct category assignments.
+Since Scorecard evaluates rules in order and stops at the first match, proper sequencing is essential for accurate health classification.
 
 == Evaluation order for rules
 

modules/observe/scorecards/con-how-thresholds-work.adoc

@@ -1,7 +1,7 @@
 :_mod-docs-content-type: CONCEPT
 
 [id="con-how-thresholds-work_{context}"]
-= How Thresholds work
+= Scorecard metric threshold categorization rules
 
 A threshold defines conditions or expressions to assign metric values to specific visual categories.
 

modules/observe/scorecards/con-manage-metric-thresholds-in-scorecard-plugin.adoc

@@ -1,6 +1,6 @@
 :_mod-docs-content-type: CONCEPT
 
 [id="con-manage-metric-thresholds-in-scorecard-plugin_{context}"]
-= Managing metric thresholds in your Scorecard plugin
+= Scorecard metric thresholds
 
-The Scorecard plugin uses thresholds to translate raw metric values into visual health indicators (`Success`, `Warning`, or `Error`). Configuring these thresholds is the primary way platform engineers and developers define what constitutes a healthy component.
+You can configure thresholds to turn raw metrics into meaningful health indicators, such as `Success`, `Warning`, or `Error`, helping you identify healthy components and detect issues early.

modules/observe/scorecards/con-set-global-standards-for-metric-thresholds.adoc

@@ -1,13 +1,13 @@
 :_mod-docs-content-type: CONCEPT
 
 [id="con-set-global-standards-to-configure-thresholds"]
-= Set global standards for metric thresholds
+= Standardize Scorecard metric thresholds across components
 
-To override the default thresholds set by a metric provider, you must update your {product-very-short} `{my-app-config-file}` file under the configuration path of the specific metric.
+You can define global thresholds in your `{product-very-short} {my-app-config-file}` file to standardize health indicators across all components. Global configurations replace the default thresholds provided by a metric source.
 
-The custom configuration completely replaces the provider's defaults. If you omit a threshold category (such as `success`), that category is not assigned.
+If you omit a threshold category, such as `success`, the Scorecard plugin does not assign that category to the metric.
 
-The following configuration defines a `success` threshold as 10 or fewer issues, which applies to all components using the `jira.open_issues` metric unless explicitly overridden by an entity annotation.
+The following example defines thresholds for the `jira.open_issues` metric. These settings apply to all components using this metric unless an entity annotation overrides them.
 
 [source,yaml]
 ----
@@ -18,9 +18,9 @@ scorecard:
         thresholds:
           rules:
             - key: success
-              expression: '<10'    # fewer than 10 open issues is Success
+              expression: '<10'    # fewer than 10 open issues
             - key: warning
-              expression: '10-50'    # Between 10 and 50 is a Warning
+              expression: '10-50'    # Between 10 and 50 open issues
             - key: error
-              expression: '>50'      # More than 50 open issues is an Error
+              expression: '>50'      # More than 50 open issues
 ----

modules/observe/scorecards/con-understand-scorecard-plugins.adoc

@@ -1,20 +1,17 @@
 :_mod-docs-content-type: CONCEPT
 
 [id="con-understand-scorecard-plugin_{context}"]
-= Understand Scorecard plugins in {product}
+= Component health and compliance monitoring using Scorecards
 
 include::{docdir}/artifacts/snip-developer-preview-scorecard.adoc[]
 
-The Scorecard plugin offers comprehensive, customizable insights into the health, security posture, and compliance of your components, services, and APIs. It centralizes Key Performance Indicators (KPIs) within {product} ({product-very-short}), so you do not have to consult multiple external systems.
+You can use the Scorecard plugin in {product} {product-very-short} to quickly assess the health, security, and compliance of your services in one place. By bringing key performance indicators together in a single view, you can evaluate component quality and identify issues without jumping between multiple tools or systems.
 
-The Scorecard plugin offers the following benefits:
+Use the Scorecard plugin to achieve the following goals:
 
-* Accelerated decision-making: Scorecards provide an at-a-glance view of component readiness. Engineering and platform teams can use this data to quickly identify risks and prioritize remediation efforts, enabling faster, more effective decisions.
-
-* Improved security and compliance: The plugin automatically surfaces compliance gaps against predefined standards (such as required security checks). This capability enforces best practices and helps maintain a stronger overall security posture.
-
-* Reduced context switching: Centralizing all KPIs in {product-very-short} reduces the time developers spend hunting for data across different tools. Developers can then focus more on building and shipping features.
-
-* Standardization and consistency: Scorecards help drive organizational consistency by clearly defining and measuring what "good" looks like for every service. This process fosters a more uniform and reliable ecosystem.
+* Identify and prioritize risks: Use unified health data to make faster remediation decisions.
+* Maintain security standards: Automatically surface compliance gaps to enforce best practices.
+* Streamline workflows: Access all metrics in {product-very-short} to reduce development overhead.
+* Standardize service quality: Define and measure consistent health criteria across the organization.
 
 image::rhdh/scorecard-sample.png[]

modules/observe/scorecards/proc-authenticating-and-managing-scorecard-plugins.adoc

@@ -1,17 +1,17 @@
 :_mod-docs-content-type: PROCEDURE
 
 [id="proc-authenticating-and-managing-scorecard-plugins_{context}"]
-= Authenticating and managing Scorecard plugins to control who sees the metrics
+= Installing and configuring Scorecard to view metrics
 
-As an administrator, you can secure the connection to your metric providers by managing user access to the Scorecards using the Role-Based Access Control (RBAC) permissions. For users to view the Scorecard metrics, you must grant users with read access to the Scorecard metrics. You can configure these permissions either by modifying your RBAC CSV file directly or by using the RBAC Web UI.
+To enable users to view Scorecard metrics, you need to grant read access using Role-Based Access Control (RBAC). You can configure these permissions either through the RBAC CSV file or the RBAC UI, depending on how you manage access in your environment.
 
 .Prerequisite
  * You have {authorization-book-link}#enabling-and-giving-access-to-rbac[enabled RBAC, have a policy administrator role in {product-very-short}, and have added `scorecard` to plugins with permission].
 
 .Procedure
-Use any of the following methods to set the required RBAC permissions:
+Grant the required permissions by using one of the following methods:
 
-* To use the CSV file, in your CSV file, you can directly add the following code:
+* To use the RBAC CSV file, add the following policy to your CSV file to allow users to view metrics:
 +
 [source,yaml]
 ----
@@ -23,11 +23,11 @@ p, role:default/scorecard-viewer, catalog.entity.read, read, allow
 See {authorization-book-link}#ref-rbac-permission-policies_title-authorization[Permission policies reference].
 
 * To use the RBAC Web UI, complete the following steps:
-.. In your {product} menu, go to *Administration > RBAC*.
-.. Select or create the *Role* to which you want to grant access to the Scorecards.
-.. To enable read access for the Scorecard plugin, in *Add permission policies*, select *Scorecard* from the plugins dropdown.
-.. Expand *Scorecard*, select *policy* with the following details, and click *Next*:
+.. In the {product} menu, navigate to *Administration > RBAC*.
+.. Select or create the *Role* that requires Scorecard access.
+.. In the *Add permission policies* section, select *Scorecard* from the plugins dropdown.
+.. Expand the *Scorecard* entry, select *policy* with the following details, and click *Next*:
 *** *Name*: `scorecard.metric.read`
 *** *Permission*: `read`
 +
-image::rhdh/scorecard-create-role.png[]
+image::rhdh/scorecard-create-role.png[The RBAC UI showing the scorecard.metric.read permission selected for a role.]

modules/observe/scorecards/proc-configuring-github-scorecards-in-rhdh-instance.adoc

@@ -1,15 +1,15 @@
 :_mod-docs-content-type: PROCEDURE
 
 [id="proc-configuring-github-scorecards-in-rhdh-instance_{context}"]
-= Configuring GitHub Scorecards to view GitHub metrics in your {product} instance
+= Integrating GitHub health metrics using Scorecards
 
-To achieve enhanced visibility and control over your software components, you must configure the GitHub Scorecards plugin to integrate GitHub metrics directly into your {product-very-short} catalog. This allows engineering teams to centralize development data, quickly identify risks, and accelerate decision-making related to component health and security.
+You can configure the GitHub Scorecard plugin to display repository metrics in your {product-very-short} catalog. This integration allows you to monitor component health and security risks directly from {product}.
 
-To enable the GitHub metrics integration, you must create and configure an integration to grant {product-very-short} access to the GitHub API using either a https://docs.github.com/en/apps/overview[GitHub App] or a https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens[GitHub token].
+You can grant {product-very-short} access to the GitHub API by using a https://docs.github.com/en/apps/overview[GitHub App] or a https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens[GitHub token].
 
 [IMPORTANT]
 ====
-For long-lived integrations or when accessing resources on behalf of an organization, you must use a GitHub App.
+For long-lived integrations or organizational access, you must use a GitHub App.
 ====
 
 .Prerequisites
@@ -22,9 +22,9 @@ For long-lived integrations or when accessing resources on behalf of an organiza
 .Procedure
 To install and configure GitHub Scorecards in your {product-very-short} instance, complete the following steps:
 
-. Establish GitHub API access: Choose one of the following methods to grant {product-very-short} access to the GitHub API, and then complete the required configuration procedure:
+. Grant GitHub API access: Create one of the following authentication methods:
 ** Configure using a GitHub App.
-... Create a https://docs.github.com/en/apps/overview[GitHub App] with the required permissions (Read-only for Contents to allow reading repositories) to grant access to the GitHub API, and then complete the required configuration procedure:
+... Create a https://docs.github.com/en/apps/overview[GitHub App] with the required permissions (Read-only for Contents to allow reading repositories).
 +
 [NOTE]
 ====
@@ -45,7 +45,7 @@ You must install the GitHub App on the organization (or user account) that owns
 * `GITHUB_INTEGRATION_ORGANIZATION`:: Your GitHub organization name, such as `_<your_github_organization_name>_`.
 * `GITHUB_INTEGRATION_PRIVATE_KEY_FILE`:: The saved *Private key* content.
 
-... Configure the GitHub integration in your {product-very-short} `{my-app-config-file}` file by adding the `integrations.github` section:
+... Configure the GitHub integration in your {product-very-short} `{my-app-config-file}` file by adding the authentication details to the `integrations.github` section:
 +
 [source,yaml]
 ----
@@ -61,7 +61,7 @@ integrations:
 ----
 
 ** Configure using a GitHub token.
-... Create a https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens[GitHub token] to grant {product-very-short} access to the GitHub API. Choose one of the following token types with these minimum permissions:
+... Create a https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens[GitHub token] with the following permissions:
 **** https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic[Classic Personal Access Token] (PAT): Select the `repo` scope for read/write access to private repositories.
 **** https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token[Fine-Grained Personal Access Token] (PAT):
 ***** Choose the specific repositories that {product-very-short} must access.
@@ -73,7 +73,7 @@ where:
 
 `GITHUB_TOKEN`:: The generated GitHub token.
 
-... Configure the GitHub integration in your {product-very-short} `{my-app-config-file}` file by adding the streamlined `integrations.github` section:
+... Configure the GitHub integration in your {product-very-short} `{my-app-config-file}` file by adding the authentication details to the `integrations.github` section:
 +
 [source,yaml]
 ----
@@ -83,7 +83,7 @@ integrations:
       token: ${GITHUB_TOKEN}
 ----
 
-. Install the GitHub Scorecard plugin by adding the following code to your {product-very-short} `dynamic-plugins-config.yaml` file:
+. Enable the GitHub Scorecard plugin: Add the GitHub Scorecard module to your {product-very-short} `dynamic-plugins-config.yaml` file:
 +
 [source,yaml]
 ----
@@ -92,7 +92,7 @@ plugins:
     disabled: false
 ----
 
-. Link a component to the GitHub data source by editing the `catalog-info.yaml` file for your {product-very-short} entity and adding the required annotations as shown in the following code:
+. Annotate catalog entities: Link a component to the GitHub data source by editing the `catalog-info.yaml` file for your {product-very-short} entity and adding the required annotations as shown in the following code:
 +
 [source,yaml]
 ----
@@ -122,17 +122,17 @@ where:
 You must add the team entity to the Catalog to ensure the provided permissions are applicable.
 ====
 
-. **Statically ingest the catalog entity** by adding the `catalog.locations` section in your {product-very-short} `{my-app-config-file}` file that links to the `catalog-info.yaml` file:
+. Ingest the catalog entity: Add the location of your `catalog-info.yaml` to the `catalog.locations` section in your {product-very-short} `{my-app-config-file}` file:
 +
 [source,yaml]
 ----
 catalog:
   locations:
     - type: url
-      target: https://github.com/owner/repo/catalog-info.yaml
+      target: https://github.com/<owner>/<repository>/catalog-info.yaml
 ----
 
-. (Optional) Customize the thresholds for the *GitHub Open Pull Requests* (`github.open_prs`) metric by adding the following section to your {product-very-short} `{my-app-config-file}` file:
+. Optional: Customize thresholds:  Define custom roles for the *GitHub Open Pull Requests* (`github.open_prs`) metric in your {product-very-short} `{my-app-config-file}` file:
 +
 [source,yaml]
 ----