review updates

Signed-off-by: Jordan <jordan@nimblewidget.com>

Author: grokspawn

content/en/docs/Concepts/crds/clusterserviceversion.md

@@ -121,11 +121,12 @@ Use the `release` field when you need to make changes to the CSV that don't affe
 
 ### Format and Validation
 
-The `release` field must conform to the [semver prerelease format](https://semver.org/spec/v2.0.0.html#spec-item-9):
-- Dot-separated identifiers containing only alphanumerics and hyphens
+The `release` field must satisfy the following criteria:
+- Composed of dot-separated identifiers containing only alphanumerics and hyphens
 - Maximum length of 20 characters
 - **Cannot contain build metadata** (the `+` character and everything after it)
-- Examples: `1`, `alpha`, `alpha.1`, `beta-1`, `rc.2.0`
+
+Examples: `1`, `alpha`, `alpha.1`, `beta-1`, `rc.2.0`
 
 ### Example
 
@@ -161,15 +162,15 @@ Bundles are ordered using a composite version that considers both `version` and
 
 1. Bundles are first ordered by semantic version
 2. For bundles with the same version, those **with** a release are ordered **before** those **without** a release
-3. Bundles with the same version and both having releases are ordered by their release version
+3. Bundles with the same version and both having releases are ordered from highest to lowest release version
 
 ```mermaid
 graph TD
     A[Bundle Comparison] --> B{Same Version?}
     B -->|No| C[Order by Version]
     B -->|Yes| D{Both have Release?}
     D -->|No| E{Has Release?}
-    D -->|Yes| F[Order by decreasing Release]
+    D -->|Yes| F[Order by Release]
     E -->|Bundle A| G[A before B]
     E -->|Bundle B| H[B before A]
 
@@ -180,13 +181,13 @@ graph TD
     style H fill:#c3e6cb
 ```
 
-**Example ordering:**
+**Example versions in ascending order:**
 ```
 memcached-operator.v0.9.0          # version 0.9.0, no release
-memcached-operator-v0.10.0-alpha   # version 0.10.0, release "alpha"
-memcached-operator-v0.10.0-2       # version 0.10.0, release "2"
-memcached-operator-v0.10.0-1       # version 0.10.0, release "1"
 memcached-operator.v0.10.0         # version 0.10.0, no release
+memcached-operator-v0.10.0-1       # version 0.10.0, release "1"
+memcached-operator-v0.10.0-2       # version 0.10.0, release "2"
+memcached-operator-v0.10.0-alpha   # version 0.10.0, release "alpha"
 ```
 
 ### Build Metadata Restriction

content/en/docs/Reference/catalog-templates.md

@@ -219,8 +219,8 @@ The `opm` tool provides the capability to generate a substitutes template from e
   ],
   "substitutions": [
     {
-      "name":,
-      "base":
+      "name": "",
+      "base": ""
     }
   ]
 }
@@ -568,9 +568,7 @@ schema: olm.channel
 
 ## Substitutes Template
 
-The substitutes template provides a safe and structured way to replace bundles in an upgrade graph with newer packaging versions. This is particularly useful when you need to republish a bundle with non-functional changes (documentation fixes, label updates, etc.) and want to ensure users upgrade to the new bundle.
-
-#### Problem Statement
+The substitutes template provides a safe and structured way to replace bundles in an upgrade graph with newer packaging versions. This is particularly useful when you need to republish a bundle with non-functional changes (documentation fixes, label updates, etc.) and want to ensure users can upgrade to the new bundle.
 
 Before the substitutes template, when you needed to replace a bundle in a catalog (for example, `foo.v1.0.0` with a documentation fix), you had two options:
 
@@ -597,7 +595,7 @@ When you define a substitution:
 1. The template validates that the substitute bundle has a higher composite version than the base bundle
 2. For each channel containing the base bundle, the template:
    - Adds the new bundle to the channel
-   - Move upgrade edges (replaces, skips, skipRange) from the base to the substitute
+   - Moves upgrade edges (replaces, skips, skipRange) from the base to the substitute
    - Adds a skip edge from substitute to base
    - Updates all other entries that reference the base to reference the substitute instead
 
@@ -651,7 +649,7 @@ properties:
 #### Step 2: Create New Bundle with Release
 
 You discover `foo.v1.0.0` is missing a critical annotation. 
-You 
+You: 
 1. update the bundle's annotation in `metadata/annotations.yaml`
 2. update the bundle's CSV with `spec.release` set (here set to 1)
 3. ensure that the bundle's `metadata-name` follows the format required for using release versions

content/en/docs/Reference/file-based-catalogs.md

@@ -357,7 +357,7 @@ OLM defines a handful of property types, again using the reserved `olm.*` prefix
 
 An `olm.package` property defines the package name and version. This is a required property on bundles, and there must
 be exactly one of these properties. The `packageName` must match the bundle's first-class `package` field, the
-`version` must be a valid [semantic version][semver], and it may include an optional `release` bundle packaging identifier. See the [Bundle Release Property](#bundle_release_property) section for additional format requirements and examples.
+`version` must be a valid [semantic version][semver], and the package may include an optional `release` bundle packaging field. See the [Bundle Release Property](#bundle-release-property) section for additional format requirements and examples.
 
 The `olm.package` property [cue][cuelang-spec] schema is:
 ```cue
@@ -646,7 +646,7 @@ The `olm.bundle.object` property [cue][cuelang-spec] schema is:
 #### `olm.package` with Release Version
 
 The `olm.package` property has been extended to support an optional `release` field that specifies the packaging version of a bundle. This allows catalog maintainers to distinguish between different builds of the same operator version.
-###### Use Cases for Bundle Release
+##### Use Cases for Bundle Release
 
 Use the `release` field when you need to:
 
@@ -788,8 +788,8 @@ flowchart LR
     D -->|Yes| F[Order by release]
     D -->|No| G{Which has<br/>release?}
 
-    G -->|A| H[B before A]
-    G -->|B| I[A before B]
+    G -->|A| H[B &lt; A]
+    G -->|B| I[A &lt; B]
 
     F --> J[Bundle A &lt; Bundle B<br/>1 &lt; 2]
 
@@ -806,17 +806,17 @@ flowchart LR
 **Ordering rules:**
 1. Compare by version first (using semver comparison)
 2. If versions are equal:
-   - Bundles **with** a release come **before** bundles **without** a release
+   - Bundles **with** a release are **greater than** bundles **without** a release
    - Bundles both having releases are ordered by their release version (using semver prerelease comparison)
 
-**Example ordering sequence:**
+**Example ascending order sequence:**
 ```
 foo.v0.2.0              # v0.2.0, no release
-foo-v0.3.0-2            # v0.3.0, release "2"
-foo-v0.3.0-1            # v0.3.0, release "1"
-foo-v0.3.0-beta.1       # v0.3.0, release "beta.1"
-foo-v0.3.0-alpha        # v0.3.0, release "alpha" (beta > alpha lexicographically)
 foo.v0.3.0              # v0.3.0, no release
+foo-v0.3.0-1            # v0.3.0, release "1" is greater than no release
+foo-v0.3.0-2            # v0.3.0, release "2" is greater than release "1"
+foo-v0.3.0-alpha        # v0.3.0, release "alpha" is greater than release "2"
+foo-v0.3.0-beta.1       # v0.3.0, release "beta.1" is greater than release "alpha"
 foo.v0.4.0              # v0.4.0, no release
 ```