docs: implemented suggestions

Signed-off-by: Fabrice Flore-Thébault <[email protected]>

Author: themr0c

artifacts/attributes.adoc

@@ -19,9 +19,12 @@
 :rhel: Red Hat Enterprise Linux
 :odf-name: OpenShift Data Foundation
 
+:my-app-config-config-map: my-rhdh-app-config
+:my-app-config-file: app-config.yaml
+:my-product-cr-name: my-rhdh-custom-resource
+:my-product-namespace: my-rhdh-project
+:my-product-secrets: my-rhdh-secrets
 :my-product-url: https://__<my_developer_hub_url>__
-:my-product-namespace: rhdh
-:my-product-cr-name: developer-hub
 
 // Red Hat Platforms
 :ocp-brand-name: Red Hat OpenShift Container Platform

assemblies/assembly-provisioning-a-custom-configuration.adoc

@@ -1,14 +1,30 @@
 :_mod-docs-content-type: ASSEMBLY
-:context: provisioning-and-registering-your-custom-configuration
+:context: provisioning-and-using-your-custom-configuration
 [id="{context}"]
-= Provisioning and registering your custom {product} configuration
+= Provisioning and using your custom {product} configuration
+
+To configure {product}, use these methods, which are widely used to configure a {ocp-brand-name} application:
+
+* Use config maps to mount files and directories.
+* Use secrets to inject environment variables.
+
+Learn to apply these methods to {product-short}:
+
+. xref:provisioning-your-custom-configuration[Provision your custom config maps and secrets to {ocp-short}].
+. Use your selected deployment method to mount the config maps and inject the secrets:
+
+** xref:using-the-operator-to-run-rhdh-with-your-custom-configuration[Use the {product} operator to deploy {product-short}].
+** xref:using-the-helm-chart-to-run-rhdh-with-your-custom-configuration[Use the {product} Helm chart to deploy {product-short}].
+
 
 include::modules/configuring/proc-provisioning-your-custom-configuration.adoc[leveloffset=+1]
 
-include::modules/configuring/proc-registering-your-custom-configuration-by-using-the-operator.adoc[leveloffset=+1]
+
+include::modules/configuring/proc-using-the-operator-to-run-rhdh-with-your-custom-configuration.adoc[leveloffset=+1]
+
 
 include::modules/configuring/proc-adding-custom-configuration-files-by-using-the-operator.adoc[leveloffset=+1]
 
 
-include::modules/configuring/proc-adding-custom-configuration-files-by-using-helm.adoc[leveloffset=+1]
+include::modules/configuring/proc-using-the-helm-chart-to-run-rhdh-with-your-custom-configuration.adoc[leveloffset=+1]
 

modules/getting-started/con-servicenow-custom-actions.adoc renamed to assemblies/assembly-using-servicenow.adoc

@@ -10,3 +10,8 @@ The custom actions in {product-short} enable you to facilitate and automate the
 * Create, update, or delete a record
 * Retrieve information about a single record or multiple records
 
+include::modules/using-service-now/proc-enable-servicenow-custom-actions-plugin.adoc[leveloffset=+1]
+
+
+include::modules/using-service-now/ref-supported-servicenow-custom-actions.adoc[leveloffset=+1]
+

assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc

@@ -25,10 +25,6 @@ include::../modules/dynamic-plugins/proc-topology-configure.adoc[leveloffset=+2]
 include::../assembly-bulk-importing-from-github.adoc[leveloffset=+1]
 
 
-include::../modules/getting-started/con-servicenow-custom-actions.adoc[leveloffset=+1]
+include::../assembly-using-servicenow.adoc[leveloffset=+1]
 
 
-include::../modules/getting-started/proc-enable-servicenow-custom-actions-plugin.adoc[leveloffset=+2]
-
-
-include::../modules/getting-started/ref-supported-servicenow-custom-actions.adoc[leveloffset=+2]

modules/configuring/proc-adding-custom-configuration-files-by-using-the-operator.adoc

@@ -1,5 +1,5 @@
 [id="proc-add-custom-app-config-file-ocp-operator_{context}"]
-= Adding your custom {product} configuration to a running {product-short} by using the operator
+= Using the {product} operator to add your custom configuration to a running {product-short}
 
 Reference your custom config maps and secrets in your `Backstage` custom resource
 to redeploy your running {product} instance with your custom configuration by using the {product-short} operator.
@@ -18,7 +18,7 @@ image::{imagesdir}/rhdh/operator-install-2.png[]
 
 . In the custom resource, enter the name of the custom application configuration config map as the value for the `spec.application.appConfig.configMaps` field, and enter the name of your secret as the value for the `spec.application.extraEnvs.secrets` field. For example:
 +
-[source, yaml]
+[source,yaml,subs="+attributes,+quotes"]
 ----
 apiVersion: rhdh.redhat.com/v1alpha1
 kind: Backstage
@@ -29,10 +29,10 @@ spec:
     appConfig:
       mountPath: /opt/app-root/src
       configMaps:
-         - name: app-config
+         - name: {my-app-config-config-map}
     extraEnvs:
       secrets:
-         - name: my-rhdh-secrets
+         - name: {my-product-secrets}
     extraFiles:
       mountPath: /opt/app-root/src
     replicas: 1

modules/configuring/proc-provisioning-your-custom-configuration.adoc

@@ -11,6 +11,7 @@ Your changes on this configuration might get reverted on {product-short} restart
 
 .Prerequisites
 * By using the link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/cli_tools/index#cli-about-cli_cli-developer-commands[{openshift-cli}], you have access, with developer permissions, to the {ocp-short} cluster aimed at containing your {product-short} instance.
+
 * You know your desired {product-short} external URL: pass:c,a,q[{my-product-url}].
 +
 [TIP]
@@ -24,18 +25,18 @@ To identify your {product-short} external URL:
 
 
 .Procedure
-. Author your custom `secrets.txt` file to provision your secrets as environment variables values in an {ocp-short} secret, rather than in clear text in your configuration files.
+. Author your custom `{my-product-secrets}.txt` file to provision your secrets as environment variables values in an {ocp-short} secret, rather than in clear text in your configuration files.
 It contains one secret per line in `KEY=value` form.
 
 .. To define the {product-short} backend secret, add the `BACKEND_SECRET` environment variable with a base64 encoded string.
 Use a unique value for each {product-short} instance.
 +
 [source,terminal,subs="+attributes"]
 ----
-$ echo > secrets.txt "BACKEND_SECRET=$(node -p 'require("crypto").randomBytes(24).toString("base64")')"
+$ echo > {my-product-secrets}.txt "BACKEND_SECRET=$(node -p 'require("crypto").randomBytes(24).toString("base64")')"
 ----
 +
-.`secrets.txt` example
+.`{my-product-secrets}.txt` example
 ====
 ----
 BACKEND_SECRET=3E2/rIPuZNFCtYHoxVP8wjriffnN1q/z
@@ -44,10 +45,10 @@ BACKEND_SECRET=3E2/rIPuZNFCtYHoxVP8wjriffnN1q/z
 
 .. Optionally, link:{authentication-book-url}[add authentication secrets].
 
-. Author your custom `app-config.yaml` file.
+. Author your custom `{my-app-config-file}` file.
 This is the main {product-short} configuration file.
 +
-.Minimal `app-config.yaml` example
+.Minimal `{my-app-config-file}` example
 ====
 [source,yaml,subs="+attributes,+quotes"]
 ----
@@ -72,16 +73,16 @@ Enter your {product-short} general configuration in the `app` section.
 
 app.title::: Enter your {product-short} instance display name, such as _<{product}>_.
 +
-.`app-config.yaml` excerpt
-[source,yaml,subs="attributes+"]
+.`{my-app-config-file}` excerpt
+[source,yaml,subs="+attributes,+quotes"]
 ----
 app:
   title: {product}
 ----
 
 app.baseURL::: Enter your {product-short} external URL, such as pass:c,a,q[{my-product-url}].
 +
-.`app-config.yaml` excerpt
+.`{my-app-config-file}` excerpt
 [source,yaml,subs="+attributes,+quotes"]
 ----
 app:
@@ -98,7 +99,7 @@ Enter your {product-short} backend configuration in the `backend` section.
 backend.auth::: Enter your authentication configuration.
 See link:{authentication-book-url}[{authentication-book-title}].
 +
-.`app-config.yaml` excerpt
+.`{my-app-config-file}` excerpt
 [source,yaml,subs="+attributes,+quotes"]
 ----
 backend:
@@ -108,7 +109,7 @@ backend:
 backend.auth.externalAccess:::
 Enter the mandatory backend authentication key configuration.
 +
-.`app-config.yaml` excerpt
+.`{my-app-config-file}` excerpt
 [source,yaml,subs="+attributes,+quotes"]
 ----
 backend:
@@ -122,7 +123,7 @@ backend:
 
 backend.baseURL and backend.cors.origin::: Enter your {product-short} external URL, such as pass:c,a,q[{my-product-url}].
 +
-.`app-config.yaml` excerpt
+.`{my-app-config-file}` excerpt
 [source,yaml,subs="+attributes,+quotes"]
 ----
 backend:
@@ -154,27 +155,26 @@ $ oc create namespace {my-product-namespace}
 +
 Alternatively, link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/building_applications/index#creating-a-project-using-the-web-console_projects[create the project by using the web console].
 
-.. Provision your `app-config.yaml` file to the `app-config` config map.
+.. Provision your `{my-{my-app-config-config-map}-file}` file to the `{my-app-config-config-map}` config map in the _<{my-product-namespace}>_ project.
 +
-[source,terminal]
+[source,terminal,subs="+attributes,+quotes"]
 ----
-$ oc create configmap app-config --from-file=app-config.yaml
+$ oc create configmap {my-app-config-config-map} --from-file={my-app-config-file} --namespace={my-product-namespace}
 ----
 +
 Alternatively, link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/nodes/index#nnodes-pods-configmap-create-from-console_configmaps[create the config map by using the web console].
 
-.. Provision your `secrets.txt` to the `my-rhdh-secrets` secret.
+.. Provision your `{my-product-secrets}.txt` file to the `{my-product-secrets}` secret in the _<{my-product-namespace}>_ project.
 +
-[source,terminal]
+[source,terminal,subs="+attributes,+quotes"]
 ----
-$ oc create secret generic my-rhdh-secrets --from-file=secrets.txt
+$ oc create secret generic {my-product-secrets} --from-file={my-product-secrets}.txt --namespace={my-product-namespace}
 ----
 +
 Alternatively,
 link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/nodes/index#nodes-pods-secrets-creating-web-console-secrets_nodes-pods-secrets[create the secret by using the web console].
 
 .Next steps
-
 Consider provisioning additional config maps and secrets:
 
 * To use an external PostgreSQL database, xref:configuring-external-postgresql-databases[provision your PostgreSQL database secrets].
@@ -184,6 +184,6 @@ Consider provisioning additional config maps and secrets:
 On a development environment, consider skipping this step and using the internal PostgreSQL database.
 ====
 
-* To enable dynamic plugins, link:{installing-and-viewing-dynamic-plugins-url}[provision the dynamic plugins config map].
+* To enable dynamic plugins, link:{installing-and-viewing-dynamic-plugins-url}[provision your dynamic plugins config map].
 
-* To configure authorization by using external files, link:{authorization-book-url}#managing-authorizations-by-using-external-files[provision the RBAC policies config map].
+* To configure authorization by using external files, link:{authorization-book-url}#managing-authorizations-by-using-external-files[provision your RBAC policies config map].

modules/configuring/proc-adding-custom-configuration-files-by-using-helm.adoc renamed to modules/configuring/proc-using-the-helm-chart-to-run-rhdh-with-your-custom-configuration.adoc

@@ -1,12 +1,12 @@
-[id='proc-add-custom-app-file-openshift-helm_{context}']
-= Adding custom {product} configuration files by using the Helm chart
+[id='using-the-helm-chart-to-run-rhdh-with-your-custom-configuration']
+= Using the {product} Helm chart to run {product-short} with your custom configuration
 
 You can use the {product} Helm chart to add a custom application configuration file to your {ocp-short} instance.
 
 .Prerequisites
 
-* By using the {ocp-short} web console, you have access with developer permissions, to link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/building_applications/index#working-with-projects[an {ocp-short} project] named _<{product-very-short}>_, aimed at containing your {product-short} instance.
-* xref:provisioning-your-custom-configuration[You have uploaded your custom configuration files and secrets in your `_<{product-very-short}>_` project].
+* By using the {ocp-short} web console, you have access with developer permissions, to link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/building_applications/index#working-with-projects[an {ocp-short} project] named _<{my-product-namespace}>_, aimed at containing your {product-short} instance.
+* xref:provisioning-your-custom-configuration[You have uploaded your custom configuration files and secrets in your `_<{my-product-namespace}>_` project].
 
 .Procedure
 
@@ -17,13 +17,13 @@ You can use the {product} Helm chart to add a custom application configuration f
 .. Set the value of the `upstream.backstage.extraAppConfig.configMapRef` and `upstream.backstage.extraAppConfig.filename` parameters as follows:
 +
 .Helm configuration excerpt
-[source,yaml]
+[source,yaml,subs="+attributes,+quotes"]
 ----
 upstream:
   backstage:
     extraAppConfig:
-      - configMapRef: app-config
-        filename: app-config.yaml
+      - configMapRef: {my-app-config-config-map}
+        filename: {my-app-config-file}
 ----
 .. Click *Upgrade*.