Addressed review comments and made some more minor edits

abhatt-rh · abhatt-rh · commit ff384ba24913 · 2023-11-16T00:09:09.000Z
diff --git a/.vale.ini b/.vale.ini
@@ -0,0 +1,17 @@
+StylesPath = .vale/styles
+
+MinAlertLevel = suggestion
+
+Packages = RedHat, AsciiDoc
+Vocab = OpenShiftDocs
+
+# Ignore files in dirs starting with `.` to avoid raising errors for `.vale/fixtures/*/testinvalid.adoc` files
+[[!.]*.adoc]
+BasedOnStyles = RedHat, AsciiDoc,
+
+# Optional: pass doc attributes to asciidoctor before linting
+#[asciidoctor]
+#openshift-enterprise = YES
+
+# Disabling rules (NO)
+RedHat.ReleaseNotes = NO
diff --git a/modules/med-about-cluster-sizing.adoc b/modules/med-about-cluster-sizing.adoc
@@ -5,7 +5,7 @@
 [id="about-openshift-cluster-sizing-med"]
 = About OpenShift cluster sizing for the {med-pattern}
 
-To understand cluster sizing requirements for the {med-pattern}, consider the following components that the {med-pattern} deploys on the datacenter or the hub OpenShift cluster:
+The {med-pattern} deploys the following components on the datacenter or the hub OpenShift cluster:
 
 |===
 | Name | Kind | Namespace | Description
diff --git a/modules/med-about-customizing-pattern.adoc b/modules/med-about-customizing-pattern.adoc
@@ -4,14 +4,20 @@
 [id="about-customizing-pattern-med"]
 = About customizing the {med-pattern}
 
-One of the major goals of the {solution-name-upstream} development process is to create modular and customizable demos. The {med-pattern} is just an example of how AI/ML workloads built for object detection and classification can be run on OpenShift clusters. Consider your workloads for a moment - how would your workload best consume the pattern framework? Do your consumers require on-demand or near real-time responses when using your application? Is your application processing images or data that is protected by either Government Privacy Laws or HIPAA?
-The {med-pattern} can answer the call to either of these requirements by using  {serverless-short} and {ocp-data-short}.
+One of the major goals of the {solution-name-upstream} development process is to create modular and customizable demos. The {med-pattern} is just an example of how AI/ML workloads built for object detection and classification can be run on OpenShift clusters. Consider your workloads for a moment:
+* How would your workload best consume the pattern framework?
+
+* Do your consumers require on-demand or near real-time responses when using your application?
+
+* Is your application processing images or data that is protected by either Government Privacy Laws or HIPAA?
+
+The {med-pattern} can address either of these requirements by using  {serverless-short} and {ocp-data-short}.
 
 [id="understanding-different-ways-to-use-med-pattern"]
 == Understanding different ways to use the {med-pattern}
 
-* The {med-pattern} is scanning X-Ray images to determine the probability that a patient might or might not have Pneumonia. Continuing with the medical path, the pattern could be used for other early detection scenarios that use object detection and classification. For example, the pattern could be used to scan C/T images for anomalies in the body such as Sepsis, Cancer, or even benign tumors. Additionally, the pattern could be used for detecting blood clots, some heart disease, and bowel disorders like Crohn's disease.
-* The Transportation Security Agency (TSA) could use the {med-pattern} in a way that enhances their existing scanning capabilities to detect with a higher probability restricted items carried on a person or hidden away in a piece of luggage. With Machine Learning Operations (MLOps), the model is constantly training and learning to better detect those items that are dangerous but which are not necessarily metallic, such as a firearm or a knife. The model is also training to dismiss those items that are authorized; ultimately saving passengers from being stopped and searched at security checkpoints.
+* The {med-pattern} is scanning X-ray images to determine the probability that a patient might or might not have pneumonia. Continuing with the medical path, the pattern could be used for other early detection scenarios that use object detection and classification. For example, the pattern could be used to scan computed tomography (CT) images for anomalies in the body such as sepsis, cancer, or even benign tumors. Additionally, the pattern could be used for detecting blood clots, some heart disease, and bowel disorders like Crohn's disease.
+* The United States Transportation Security Agency (TSA) could use the {med-pattern} in a way that enhances their existing scanning capabilities to detect with a higher probability restricted items carried on a person or hidden away in a piece of luggage. With Machine Learning Operations (MLOps), the model is constantly training and learning to better detect those items that are dangerous but which are not necessarily metallic, such as a firearm or a knife. The model is also training to dismiss those items that are authorized, which can save passengers from being stopped and searched at security checkpoints.
 * Militaries could use images collected from drones, satellites, or other platforms to identify objects and determine with probability what that object is. For example, the model could be trained to determine a type of ship, potentially its country of origin, and other such identifying characteristics.
 * Manufacturing companies could use the pattern to inspect finished products as they roll off a production line. An image of the item, including using different types of light, could be analyzed to help expose defects before packaging and distributing. The item could be routed to a defect area.
 
diff --git a/modules/med-about-makefile.adoc b/modules/med-about-makefile.adoc
@@ -2,30 +2,30 @@
 :imagesdir: ../../images
 
 [id="med-understanding-the-makefile-troubleshooting"]
-=== Understanding the Makefile
+= Understanding the Makefile
 
-The Makefile is the entrypoint for the pattern. We use the Makefile to bootstrap the pattern to the cluster. After the initial bootstrapping of the pattern, the Makefile isn't required for ongoing operations but can often be useful when needing to make a change to a config within the pattern by running a `make upgrade` which allows us to refresh the bootstrap resources without having to tear down the pattern or cluster.
+The Makefile is the entrypoint for the pattern. We use the Makefile to bootstrap the pattern to the cluster. After the initial bootstrapping of the pattern, the Makefile isn't required for ongoing operations but can often be useful when you need to make a change to a config within the pattern. Run the `make upgrade` command to refresh the bootstrap resources without having to tear down the pattern or cluster.
 
 [id="about-make-install-make-deploy-command"]
-==== About the make install and make deploy commands
+== About the make install and make deploy commands
 
-Running `make install` within the pattern application triggers a `make deploy` from `<pattern_directory>/common` directory. This initializes the `common` components of the pattern framework and install a helm chart in the `default` namespace. At this point, cluster services, such as {rh-rhacm-first} and {rh-gitops} are deployed.
+Running `make install` within the pattern application triggers a `make deploy` from `<pattern_directory>/common` directory. This initializes the `common` components of the pattern framework and installs a Helm chart in the `default` namespace. At this point, cluster services, such as {rh-rhacm-first} and {rh-gitops} are deployed.
 
-After components from the `common` directory are installed, the remaining tasks within the `make install` target run.
+After you have installed the components from the `common` directory, the pattern runs the remaining tasks within the `make install` target.
 //AI: Check which are these other tasks
 
 [id="about-make-vault-init-make-load-secrets-commands"]
-==== About the make vault-init and make load-secrets commands
+== About the make vault-init and make load-secrets commands
 
 The {med-pattern} is integrated with {hashicorp-vault} and {eso-op} services for secrets management within the cluster. These targets install vault from a {helm-chart} and load the secret `(values-secret.yaml)` that you created during link:../med-getting-started/#preparing-for-deployment[Getting Started].
 
-If `values-secret.yaml` does not exist, make will exit with an error saying so. Furthermore, if the `values-secret.yaml` file does exist but is improperly formatted, {rh-ansible} exits with an error about being improperly formatted. To verify the format of the secret, see link:../med-getting-started/#preparing-for-deployment[Getting Started].
+If `values-secret.yaml` does not exist, `make` will exit with an error saying so. Furthermore, if the `values-secret.yaml` file does exist but is improperly formatted, {rh-ansible} exits with an error about being improperly formatted. To verify the format of the secret, see link:../med-getting-started/#preparing-for-deployment[Getting Started].
 
 [id="about-make-bootstrap-make-upgrade-commands"]
-==== About the make bootstrap and make upgrade commands
+== About the make bootstrap and make upgrade commands
 The `make bootstrap` command is the target used for deploying the application specific components of the pattern. It is the final step in the initial `make install` target. You might want to consider running the `make upgrade` command instead of the `make bootstrap` command directly.
 
-Generally, running the `make upgrade` command is required when you encounter errors with the application pattern deployment. For instance, if a value was missed and the chart was not rendered correctly, executing `make upgrade` command after fixing the value would be necessary.
+Generally, running the `make upgrade` command is required when you encounter errors with the application pattern deployment. For example, if you miss a value and the chart does not rendered correctly, you must execute the run the `make upgrade` command after fixing the value.
 
-You might want to review the `Makefile` for the `common` and `Medical Diagnosis` components, which are located in `common/Makefile` and `./Makefile` respectively.
+Review the `Makefile` for the `common` and `Medical Diagnosis` components, which are located in `common/Makefile` and `./Makefile` respectively.
 
diff --git a/modules/med-about-medical-diagnosis.adoc b/modules/med-about-medical-diagnosis.adoc
@@ -6,7 +6,7 @@
 
 Background::
 
-This validated pattern is based on a demo implementation of an automated data pipeline for chest X-ray analysis that was previously developed by {redhat}. You can find the original demonstration link:https://github.com/red-hat-data-services/jumpstart-library[here]. It was developed for the US Department of Veteran Affairs.
+This validated pattern is based on a demo implementation of an automated data pipeline for chest X-ray analysis that {redhat} developed for the US Department of Veteran Affairs. You can find the original demonstration link:https://github.com/red-hat-data-services/jumpstart-library[here].
 
 This validated pattern includes the same functionality as the original demonstration. The difference is that this solution uses the GitOps framework to deploy the pattern including Operators, creation of namespaces, and cluster configuration. Using GitOps provides an efficient means of implementing continuous deployment.
 
diff --git a/modules/med-deploying-med-diag-pattern.adoc b/modules/med-deploying-med-diag-pattern.adoc
@@ -11,15 +11,15 @@
 $ ./pattern.sh make install
 ----
 +
-If the installation fails, you can go over the instructions and make updates, if required.
+If the installation fails, review the instructions and make any required updates.
 To continue the installation, run the following command:
 +
 [source,terminal]
 ----
 $ ./pattern.sh make update
 ----
 +
-This step might take some time, especially for the {ocp-data-short} Operator components to install and synchronize. The `./pattern.sh make install` command provides some progress updates during the installation process. It can take up to twenty minutes. Compare your `./pattern.sh make install` run progress with the following video that shows a successful installation.
+This step might take up to twenty minutes to complete, especially for the {ocp-data-short} Operator components to install and synchronize. The `./pattern.sh make install` command provides some progress updates during the installation process. It can take up to twenty minutes. Compare your `./pattern.sh make install` run progress with the following video that shows a successful installation.
 +
 image::/videos/xray-deployment.svg[link="/videos/xray-deployment.svg"]
 
diff --git a/modules/med-ocp-cluster-sizing.adoc b/modules/med-ocp-cluster-sizing.adoc
@@ -6,12 +6,15 @@
 
 The {med-pattern} has been tested with a defined set of configurations that represent the most common combinations that {ocp} customers are using for the x86_64 architecture.
 
-For {med-pattern}, the OpenShift cluster size must be a bit larger to support the compute and storage demands of OpenShift Data Foundations and other Operators.
+For {med-pattern}, the OpenShift cluster size must be larger than a standard cluster to support the compute and storage demands of OpenShift Data Foundations and other Operators.
 
-The minimum requirements for an {ocp} cluster depend on your installation platform. For instance, for AWS, see link:https://docs.openshift.com/container-platform/4.13/installing/installing_aws/preparing-to-install-on-aws.html#requirements-for-installing-ocp-on-aws[Installing {ocp} on AWS], and for bare-metal, see link:https://docs.openshift.com/container-platform/4.13/installing/installing_bare_metal/installing-bare-metal.html#installation-minimum-resource-requirements_installing-bare-metal[Installing {ocp} on bare metal].
+The minimum requirements for an {ocp} cluster depend on your installation platform, for example:
 
-For information about requirements for additional platforms, see link:https://docs.openshift.com/container-platform/4.13/installing/installing-preparing.html[{ocp} documentation].
+* For AWS, see link:https://docs.openshift.com/container-platform/4.13/installing/installing_aws/preparing-to-install-on-aws.html#requirements-for-installing-ocp-on-aws[Installing {ocp} on AWS]
+
+* For bare-metal, see link:https://docs.openshift.com/container-platform/4.13/installing/installing_bare_metal/installing-bare-metal.html#installation-minimum-resource-requirements_installing-bare-metal[Installing {ocp} on bare metal].
 
+For information about requirements for additional platforms, see link:https://docs.openshift.com/container-platform/4.13/installing/installing-preparing.html[{ocp} documentation].
 
 [NOTE]
 ====
diff --git a/modules/med-preparing-for-deployment.adoc b/modules/med-preparing-for-deployment.adoc
@@ -72,7 +72,7 @@ By default, Vault password policy generates the passwords for you. However, you
 +
 [NOTE]
 ====
-When defining a custom password for the database users, avoid using the `$` special character because it gets interpreted by the shell and will ultimately set the incorrect desired password.
+When defining a custom password for the database users, avoid using the `$` special character because it gets interpreted by the shell and will ultimately set the incorrect password.
 ====
 
 . To customize the deployment for your cluster, update the `values-global.yaml` file by running the following commands:
@@ -105,6 +105,8 @@ Replace instances of PROVIDE_ with your specific configuration
      bucketBaseName: "xray-source"
 ----
 +
+Save the values-global.yaml file and commit it to your branch:
+
 [source,terminal]
 ----
 $ git add values-global.yaml
@@ -137,7 +139,7 @@ Optional: Set the `KUBECONFIG` variable for the `kubeconfig` file path:
 
 .Verification
 
-To ensure that you have the required variables to deploy the {med-pattern}, run the `./pattern.sh make predeploy` command. You can review your values and make updates, if required.
+To ensure that you have the required variables to deploy the {med-pattern}, run the `./pattern.sh make predeploy` command. You can review your values and m0ake any required updates.
 
 You must review the following `values*` files before deploying the {med-pattern}:
 
diff --git a/modules/med-setup-aws-s3-bucket-with-utilities.adoc b/modules/med-setup-aws-s3-bucket-with-utilities.adoc
@@ -28,5 +28,5 @@ $ python s3-sync-buckets.py -s validated-patterns-md-xray -t mytest-bucket -r us
 
 image:/videos/bucket-setup.svg[Bucket setup]
 
-Make a note of the name and the URL for the bucket for further pattern configuration. For example, you must update these values in a `values-global.yaml` file, where there is a section for `s3:`
+Make a note of the name and the URL for the bucket for further pattern configuration. For example, you must update these values in a `values-global.yaml` file, where there is a section for `s3:`.
 
diff --git a/modules/med-troubleshooting-deployment.adoc b/modules/med-troubleshooting-deployment.adoc
@@ -2,7 +2,7 @@
 :imagesdir: ../../../images
 
 [id="troubleshooting-the-pattern-deployment-troubleshooting"]
-=== Troubleshooting the pattern deployment
+= Troubleshooting the pattern deployment
 
 Occasionally the pattern will encounter issues during the deployment. This can happen for any number of reasons, but most often it is because of either a change within the operator itself or something has changed in the {olm-first} which determines which operators are available in the operator catalog. Generally, when an issue occurs with the {olm-short}, the operator is unavailable for installation. To ensure that the operator is in the catalog, run the following command:
 
@@ -23,7 +23,7 @@ Use the grafana dashboard to assist with debugging and identifying the issue
 '''
 Problem:: No information is being processed in the dashboard
 
-Solution:: Most often this is due to the image-generator deploymentConfig needing to be scaled up. The image-generator by design is *scaled to 0*;
+Solution:: Solution:: Most often this is due to the image-generator deploymentConfig needing to be scaled up. The image-generator by design is *scaled to 0*":
 +
 [source,terminal]
 ----
@@ -97,7 +97,7 @@ MariaDB [xraylabdb]> show tables;
 3 rows in set (0.000 sec)
 ----
 +
-. Verify the password set in the `values-secret.yaml` is working
+. Verify the password set in the `values-secret.yaml` is working:
 +
 [source,terminal]
 ----
diff --git a/modules/med-viewing-grafana-dashboard.adoc b/modules/med-viewing-grafana-dashboard.adoc
@@ -16,33 +16,35 @@ image::medical-edge/storage-rgw-route.png[link="/images/medical-edge/storage-rgw
 +
 image::medical-edge/grafana-routes.png[link="/images/medical-edge/grafana-routes.png"]
 
-. Turn on the image file flow. There are three ways to go about this.
+. Turn on the image file flow. There are three methods to do this.
 +
-You can go to the command-line (make sure you have KUBECONFIG set, or are logged into the cluster.
+--
+* Method 1: Go to the command-line and log into the cluster. Ensure you have exported the `KUBECONFIG` file.
 +
 [source,terminal]
 ----
 $ oc scale deploymentconfig/image-generator --replicas=1 -n xraylab-1
 ----
 +
-Or you can go to the OpenShift UI and change the view from Administrator to Developer and select Topology. From there select the `xraylab-1` project.
+* Method 2: Go to the {opc} web console and change the view from *Administrator* perspective to *Developer* perspective and select *Topology*. From there select the `xraylab-1` project.
 +
 image::medical-edge/dev-topology.png[link="/images/medical-edge/dev-topology.png"]
 +
 Right-click on the `image-generator` pod icon and select `Edit Pod count`.
 +
 image::medical-edge/dev-topology-menu.png[link="/images/medical-edge/dev-topology-menu.png"]
 +
-Up the pod count from `0` to `1` and save.
+Increase the pod count from `0` to `1` and save.
 +
 image::medical-edge/dev-topology-pod-count.png[link="/images/medical-edge/dev-topology-pod-count.png"]
 +
-Alternatively, you can have the same outcome on the Administrator console.
+* Method 3: Go to the {opc} web console and change to the *Administrator* perspective.
 +
-Go to the OpenShift UI under Workloads, select Deploymentconfigs for Project `xraylab-1`.
+Under *Workloads*, select *DeploymentConfigs* for *Project:xraylab-1*.
 Click `image-generator` and increase the pod count to 1.
 +
 image::medical-edge/start-image-flow.png[link="/images/medical-edge/start-image-flow.png"]
+--
 
 [id="customizing-dashboard"]
 == Customizing the dashboard

Original file line number	Diff line number	Diff line change
`@@ -11,15 +11,15 @@`
`11`	`11`	`$ ./pattern.sh make install`
`12`	`12`	`----`
`13`	`13`	`+`
`14`		`-If the installation fails, you can go over the instructions and make updates, if required.`
	`14`	`+If the installation fails, review the instructions and make any required updates.`
`15`	`15`	`To continue the installation, run the following command:`
`16`	`16`	`+`
`17`	`17`	`[source,terminal]`
`18`	`18`	`----`
`19`	`19`	`$ ./pattern.sh make update`
`20`	`20`	`----`
`21`	`21`	`+`
`22`		-This step might take some time, especially for the {ocp-data-short} Operator components to install and synchronize. The `./pattern.sh make install` command provides some progress updates during the installation process. It can take up to twenty minutes. Compare your `./pattern.sh make install` run progress with the following video that shows a successful installation.
	`22`	+This step might take up to twenty minutes to complete, especially for the {ocp-data-short} Operator components to install and synchronize. The `./pattern.sh make install` command provides some progress updates during the installation process. It can take up to twenty minutes. Compare your `./pattern.sh make install` run progress with the following video that shows a successful installation.
`23`	`23`	`+`
`24`	`24`	`image::/videos/xray-deployment.svg[link="/videos/xray-deployment.svg"]`
`25`	`25`
Original file line number	Diff line number	Diff line change
`@@ -28,5 +28,5 @@ $ python s3-sync-buckets.py -s validated-patterns-md-xray -t mytest-bucket -r us`
`28`	`28`
`29`	`29`	`image:/videos/bucket-setup.svg[Bucket setup]`
`30`	`30`
`31`		-Make a note of the name and the URL for the bucket for further pattern configuration. For example, you must update these values in a `values-global.yaml` file, where there is a section for `s3:`
	`31`	+Make a note of the name and the URL for the bucket for further pattern configuration. For example, you must update these values in a `values-global.yaml` file, where there is a section for `s3:`.
`32`	`32`