Incorporated Dominika's comments and rebased branch

Author: pabel-rh

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

@@ -13,30 +13,25 @@ You can view GitHub metrics for software components registered in the {product-v
 * You must have {configuring-book-link}[added a custom {product-very-short} application configuration] and have enough permissions to change it.
 
 .Procedure
+To configure GitHub Scorecards in your RHDH instance, complete the following steps:
 
-. Create and configure a GitHub App.
-.. Create the GitHub App with **Read-only** permissions for **Contents** to allow reading repositories.
+. To allow {product-very-short} to access the GitHub API, you must create and configure a GitHub App and add the necessary integration to your configuration file by completing the following steps:
+.. Create a https://docs.github.com/en/apps/overview[GitHub App] with the required permissions (Read-only for Contents to allow reading repositories).
 .. Generate a client secret and a private key.
-.. Install the app on the desired account or organization.
-.. Save the following credential values:
+.. Install the app on the desired account/organization.
+.. Save the following values:
 *** `App ID`
 *** `Client ID`
 *** `Client secret`
 *** `Private key`
+.. Add your GitHub credentials to {configuring-book-link}#provisioning-your-custom-configuration[your {product-very-short} secrets] using the following key/value pairs. You can use these secrets in the {product-very-short} configuration files by using their respective environment variable names. 
+*** `GITHUB_INTEGRATION_APP_ID`
+*** `GITHUB_INTEGRATION_CLIENT_ID`
+*** `GITHUB_INTEGRATION_CLIENT_SECRET`
+*** `GITHUB_INTEGRATION_HOST_DOMAIN` (e.g., `github.com`)
+*** `GITHUB_INTEGRATION_PRIVATE_KEY_FILE`
 
-. Add GitHub credentials to your {product-very-short} secrets.
-+
-Set the following key/value pairs as environment variables in your secrets store:
-+
-* `GITHUB_INTEGRATION_APP_ID`
-* `GITHUB_INTEGRATION_CLIENT_ID`
-* `GITHUB_INTEGRATION_CLIENT_SECRET`
-* `GITHUB_INTEGRATION_HOST_DOMAIN` (e.g., `github.com`)
-* `GITHUB_INTEGRATION_PRIVATE_KEY_FILE`
-
-. Configure the GitHub integration in your `{product-very-short} app-config.yaml`.
-+
-Add the `integrations.github` section to your custom `{product-very-short} app-config.yaml` configuration file using the environment variables:
+. Configure the GitHub integration in your `{product-very-short} app-config.yaml`, by adding the `integrations.github` section to your custom `{product-very-short} app-config.yaml` configuration file:
 +
 [source,yaml]
 ----
@@ -51,9 +46,7 @@ integrations:
             ${GITHUB_INTEGRATION_PRIVATE_KEY_FILE}
 ----
 
-. Annotate the component entity in `catalog-info.yaml`.
-+
-Link a software component to the GitHub data source by adding the required annotations to its `catalog-info.yaml` file as shown in the following example:
+. In your {product-very-short} entity that you want to configure for the GitHub Scorecard plugin, in the `catalog-info.yaml` file, link a component to the data source by adding the required annotations as shown in the following code:
 +
 [source,yaml]
 ----
@@ -82,9 +75,10 @@ Where:
 ====
 You must add the team entity to the Catalog to ensure the provided permissions are applicable.
 ====
+
 . (Optional) Configure metric threshold values.
-+
-To customize the thresholds for the **GitHub Open Pull Requests** (`github.open_prs`) metric, add the following section to your `app-config.yaml` file:
+
+.. To customize the thresholds for the **GitHub Open Pull Requests** (`github.open_prs`) metric, add the following section to your `app-config.yaml` file:
 +
 [source,yaml]
 ----
@@ -101,7 +95,8 @@ scorecard:
             - key: error
               expression: '>50'
 ----
-+
+where:
+
 `scorecard:plugins:github:open_prs:thresholds`:: Lists the default threshold values for the GitHub open PRs metric.
 
 [NOTE]

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

@@ -44,7 +44,7 @@ plugins:
 where:
 
 `baseUrl`:: Enter the Jira URL.
-`token`:: Enter the Jira token (Base64 string for Cloud, PAT for Data Center).
+`token`:: Enter the Jira token (Base64 string for Cloud, PAT for Data Center). The Jira token must be added as a secret file in your {configuring-book-link}#provisioning-your-custom-configuration[`{product} app-config.yaml` file].
 `product`:: Enter the supported product: `cloud` or `datacenter`.
 
 .. Use a proxy setup: In your `{product-very-short} dynamic-plugins-config.yaml`, add the following code: