review the product image docs

Author: lfrancke

modules/concepts/pages/product-image-selection.adoc

@@ -13,8 +13,11 @@ spec:
     productVersion: 1.2.3 <.>
     # stackableVersion: 25.7.0 # optional <.>
 ----
-<.> The version of your product. Consult the product operator documentation to find out about supported product versions.
-<.> The version of the Stackable Data Platform. If you omit it, the operator will use its own version together with the product version to select the product image. It is recommended to omit this field to ensure you are always using the correct, compatible version of the product image.
+<.> The version of your product.
+Consult the product operator documentation to find out about supported product versions.
+<.> The version of the Stackable Data Platform.
+If you omit it, the operator will use its own version together with the product version to select the product image.
+It is recommended to omit this field to ensure you are always using the correct, compatible version of the product image.
 
 == Product and Stackable version explained
 
@@ -31,7 +34,7 @@ This is the version of the product that the image provides, such as Kafka 3.9.0.
 
 TIP: You can find all products and their supported versions in the xref:operators:supported_versions.adoc[supported versions overview].
 You can also find the supported versions per product on each operator page, for example, for xref:kafka:index.adoc#_supported_versions[Apache Kafka].
-New versions, deprecations, and removals are announced in the xref:ROOT:release-notes.adoc[release notes].
+New versions, deprecations, and removals are announced in the xref:ROOT:release-notes.adoc[Stackable Data Platform release notes].
 
 **Stackable version** +
 This version tracks changes to the structure of the image containing the product (in the version specified by the _product version_).
@@ -56,14 +59,13 @@ So, an operator of version _25.7.x_ will be compatible with all images of versio
 This allows for shorter update cycles for users when new image versions are released that may contain security fixes.
 
 The following paragraphs explain the available settings and how they work.
-
 At the bottom of this page, in the <<_common_scenarios, common scenarios>> section, some common update scenarios are explained as examples.
 
 == Stackable provided images
 
-If your Kubernetes cluster has internet access, the easiest way is to use the publicly available images from the https://oci.stackable.tech/[Image registry hosted by Stackable] (as noted at the beginning of the page):
+If your Kubernetes cluster has internet access, the easiest way is to use the publicly available images from the https://oci.stackable.tech/[Stackable Image Registry].
 
-TIP: All our images are also mirrored to our https://quay.io/organization/stackable[quay.io organization].
+TIP: All our images are also mirrored to our https://quay.io/organization/stackable[Stackable Quay.io organization].
 
 [source,yaml]
 ----
@@ -72,10 +74,12 @@ spec:
     productVersion: 3.9.0 <.>
     # stackableVersion: 25.7.0 # optional <.>
 ----
-<.> The version of your product. Consult the product operator documentation to find out about supported product versions.
-<.> The version of the Stackable Data Platform. Simply omit this to use the operator version.
+<.> The version of your product.
+Consult the product operator documentation to find out about supported product versions.
+<.> The version of the Stackable Data Platform.
+Simply omit this to use the operator version.
 
-NOTE: If the Kubernetes cluster does not have internet access, a xref:_custom_docker_registry[] or xref:_custom_images[] can be used.
+NOTE: If the Kubernetes cluster does not have internet access, you can use a xref:_custom_docker_registry[] or xref:_custom_images[].
 
 You only need to specify the product version, but you _can_ also specify an explicit Stackable version.
 The product version can be found on the xref:operators:supported_versions.adoc[list of supported product versions] or on the product operator documentation page.
@@ -87,8 +91,8 @@ Security updates within a release line will result in patch version bumps in the
 If you don't specify the Stackable version, the operator will use its own version, e.g., `25.7.0`.
 When using a nightly operator or a `pr` version, it will use the nightly `0.0.0-dev` image.
 
-All the available images (with their product and Stackable versions) can be found in our https://oci.stackable.tech/api/v2.0/projects/sdp[OCI registry].
-Information on how to browse the registry can be found xref:contributor:project-overview.adoc#docker-images[here].
+All the available images (with their product and Stackable versions) can be found in our https://oci.stackable.tech/api/v2.0/projects/sdp[Stackable OCI registry].
+Information on how to browse the registry can be found in the xref:contributor:project-overview.adoc#docker-images[Docker images section of the project overview].
 
 == Custom docker registry
 
@@ -105,8 +109,7 @@ spec:
     stackableVersion: 25.7.0 # Optional
     repo: my.corp/myteam/stackable <.>
 ----
-<.> We recommend not including a slash at the end while we plan on https://github.com/stackabletech/operator-rs/issues/1020[improving the situation]
-
+<.> We recommend not including a slash at the end while we plan on https://github.com/stackabletech/operator-rs/issues/1020[improving the situation].
 
 This will change the image from the default Stackable repository `oci.stackable.tech/sdp/kafka:3.3.1-stackable23.7.0` to `my.corp/myteam/stackable/kafka:3.3.1-stackable23.7.0`.
 
@@ -131,20 +134,21 @@ Only when the correct product version is given to the operator will the product
 Using custom images has a few limitations that users should be aware of:
 
 * The images will _have_ to have the same structures that Stackable operators expect.
-This should usually be ensured by specifying a Stackable image in the `FROM` clause of the Dockerfile (all the available images can be found in our https://oci.stackable.tech/api/v2.0/projects/sdp[OCI registry] - the schema is typically: `oci.stackable.tech/sdp/<product>:<product-version>-stackable<stackable-version>`. Information on how to browse the registry can be found xref:contributor:project-overview.adoc#docker-images[here]).
+This should usually be ensured by specifying a Stackable image in the `FROM` clause of the Dockerfile (all the available images can be found in our https://oci.stackable.tech/api/v2.0/projects/sdp[Stackable OCI registry] - the schema is typically: `oci.stackable.tech/sdp/<product>:<product-version>-stackable<stackable-version>`.
+Information on how to browse the registry can be found in the xref:contributor:project-overview.adoc#docker-images[Docker images section of the project overview]).
 
 * Images will have to be upgraded for every new Stackable release to follow structural changes that Stackable may have made to their images.
 When deriving images from official Stackable images, this will mean updating the version of the image in the `FROM` clause to the correct Stackable release.
 
 * It is not possible to update the Stackable Platform to a new version without changing the deployed cluster definitions when using custom images.
 The recommended process here is:
 
-** Set `reconciliationPaused` to `true` in your product cluster (see xref:operations/cluster_operations.adoc[])
-** Update the Stackable platform
-** Change custom images in cluster specifications
-** Set `reconciliationPaused` to `false` again to start reconciliation
+** Set `reconciliationPaused` to `true` in your product cluster (see xref:operations/cluster_operations.adoc[cluster operations documentation]).
+** Update the Stackable platform.
+** Change custom images in cluster specifications.
+** Set `reconciliationPaused` to `false` again to start reconciliation.
 
-== [[common_scenarios]] Common Scenarios
+== [[common_scenarios]] Common scenarios
 
 === Planned platform updates