Merge pull request quarkusio#47408 from sheilamjones/QDOCS-1031-implement-QE-feedback

Docs: Implement QE feedback to Deploying to OpenShift guide

Author: gsmet

docs/src/main/asciidoc/deploying-to-openshift-docker-howto.adoc

@@ -4,7 +4,7 @@ and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 [id="deploying-to-openshift-docker-howto"]
-= Deploy {project-name} Java applications to {openshift} by using a Docker build strategy
+= Deploying {project-name} Java applications to {openshift} by using a Docker build strategy
 include::_attributes.adoc[]
 :diataxis-type: howto
 :categories: cloud, native

docs/src/main/asciidoc/deploying-to-openshift-howto.adoc

@@ -4,7 +4,7 @@ and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 [id="deploying-to-openshift-howto"]
-= Deploy {project-name} applications to {openshift} in a single step
+= Deploying {project-name} applications to {openshift} in a single step
 include::_attributes.adoc[]
 :diataxis-type: howto
 :categories: cloud, native
@@ -35,7 +35,7 @@ The generated resources use a Kubernetes `Deployment`, but still make use of Ope
 To run this deployment, it is not necessary to have the `quarkus-openshift` extension included in your {project-name} project.
 ====
 
-== Build and deploy in a single step
+== Procedure
 
 . Trigger a build and deployment in a single step:
 

docs/src/main/asciidoc/deploying-to-openshift-native-howto.adoc

@@ -4,8 +4,7 @@ and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 [id="deploying-to-openshift-native-howto"]
-= Deploy {project-name} applications compiled to native executables
-
+= Deploying {project-name} applications compiled to native executables
 include::_attributes.adoc[]
 :diataxis-type: howto
 :categories: cloud, native
@@ -15,17 +14,23 @@ include::_attributes.adoc[]
 
 You can deploy your native {project-name} applications to {openshift} compiled to native executables by using the Docker build strategy.
 
-You must create a native executable for your application that targets the Linux AMD64 operating system.
-If your host operating system is different from this, create a native Linux executable by using a container runtime, for example, Docker or Podman.
+You must create a native executable for your application that targets a supported operating system and match the architecture.
+This means, if you are building on Windows, you create a native Linux executable by using a container runtime, for example, Docker or Podman.
 
 Your Quarkus project includes pregenerated Dockerfiles with instructions.
 If you want to use a custom Dockerfile, add the file to the `src/main/docker` directory or any location inside the module.
-Additionally, set the path to your Dockerfile by using the `quarkus.openshift.native-dockerfile` property.
+Additionally, if you want to have multiple Docker files and switch between them, set the path to your preferred Dockerfile by using the `quarkus.openshift.native-dockerfile` property.
+
+[NOTE]
+====
+This guide describes this strategy by using a Quarkus project with Maven as the example project.
+====
 
 == Prerequisites
 
-* You have a Linux AMD64 system or an Open Container Initiative (OCI) compatible container runtime, such as Podman or Docker.
+* A supported operating system or an Open Container Initiative (OCI) compatible container runtime, such as Podman or Docker.
 * You have a Quarkus Maven project that includes the `quarkus-openshift` extension.
+* You have access to an {openshift} cluster and the latest compatible version of the `oc` CLI tool installed.
 * You are working in the correct OpenShift project namespace.
 
 == Procedure

docs/src/main/asciidoc/deploying-to-openshift-s2i-howto.adoc

@@ -183,7 +183,7 @@ For more information, see the link:https://docs.openshift.com/container-platform
 For information about this image, see link:https://catalog.redhat.com/software/containers/ubi9/openjdk-21/653fb7e21b2ec10f7dfc10d0[{runtimes-openjdk-long} 21].
 ====
 
-. To build the project, create the application, and deploy the {openshift} service, enter the following command:
+. Build the project, create the application, and deploy the {openshift} service:
 +
 [source,xml,subs="attributes+,+quotes"]
 ----

docs/src/main/asciidoc/deploying-to-openshift.adoc

@@ -3,7 +3,7 @@ This guide is maintained in the main Quarkus repository
 and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
-[id="deploy-openshift"]
+[id="deploying-to-openshift"]
 = Deploying {project-name} applications to {openshift}
 include::_attributes.adoc[]
 :categories: cloud, native
@@ -107,9 +107,10 @@ However, if you want to continue to use `DeploymentConfig`, it is still possible
 quarkus extension add 'quarkus-openshift'
 ----
 
-== Logging in to an OpenShift cluster
+== Logging in to an {openshift} cluster
 
-You can log in to an OpenShift cluster by using the https://docs.openshift.com/container-platform/4.9/cli_reference/openshift_cli/getting-started-cli.html[OpenShift CLI]:
+You can log in to an {openshift} cluster by using the OpenShift CLI (`oc`).
+For more information, see link:https://docs.openshift.com/container-platform/4.18/cli_reference/openshift_cli/getting-started-cli.html[Getting started with the OpenShift CLI]:
 
 .Example: Log in by using the OpenShift CLI
 [source,bash]
@@ -120,7 +121,7 @@ oc login -u myUsername <1>
 
 Alternatively, you can log in by using the API token:
 
-.Example: Log in by using the OpenShift command-line interface (CLI) with API token
+.Example: Log in by using the OpenShift CLI with API token
 [source,bash]
 ----
 oc login --token=myToken --server=myServerUrl
@@ -326,12 +327,12 @@ quarkus.openshift.annotations.foo=bar
 [[env-vars]]
 === Environment variables
 
-OpenShift provides multiple ways of defining environment variables:
+{openshift} provides multiple ways of defining environment variables:
 
-- key/value pairs
-- import all values from a Secret or ConfigMap
-- interpolate a single value identified by a given field in a Secret or ConfigMap
-- interpolate a value from a field within the same resource
+- Key/value pairs
+- Import all values from a Secret or ConfigMap
+- Interpolate a single value identified by a given field in a Secret or ConfigMap
+- Interpolate a value from a field within the same resource
 
 ==== Environment variables from key/value pairs
 
@@ -467,7 +468,8 @@ For example, adding the property `quarkus.openshift.arguments=A,B`.
 Finally, the Kubernetes job will be launched every time that it is installed in OpenShift.
 For more information about how to run Kubernetes jobs, see https://kubernetes.io/docs/concepts/workloads/controllers/job/#running-an-example-job[Running an example job].
 
-You can configure the rest of the Kubernetes Job configuration by using the properties under `quarkus.openshift.job.xxx` (for more information, see xref:deploying-to-openshift.adoc#quarkus-kubernetes_quarkus-openshift-job-parallelism[quarkus.openshift.job.parallelism).
+You can configure the rest of the Kubernetes Job configuration by using the properties under `quarkus.openshift.job.xxx`.
+For more information, see xref:deploying-to-openshift.adoc#quarkus-kubernetes_quarkus-openshift-job-parallelism[quarkus.openshift.job.parallelism].
 
 ===== Generating CronJob resources
 
@@ -513,13 +515,13 @@ The older syntax is still supported but is deprecated, and it is advised that yo
 
 [NOTE]
 ====
- If you redefine the same variable using the new syntax while keeping the old syntax, **ONLY** the new version is kept, and a warning will be issued to alert you of the problem.
+ If you redefine the same variable by using the new syntax while keeping the old syntax, only the new version is kept, and a warning will be issued to alert you of the problem.
  For example, if you define both `quarkus.openshift.env-vars.my-env-var.value=foobar` and `quarkus.openshift.env.vars.my-env-var=newValue`, the extension generates an environment variable `MY_ENV_VAR=newValue` and issues a warning.
 ====
 
 === Mounting volumes
 
-The OpenShift extension allows the user to configure both volumes and mounts for the application.
+The OpenShift extension allows you to configure both volumes and mounts for the application.
 You can mount any volume with a simple configuration:
 
 [source,properties]