openshift · ShaunaDiaz · Oct 15, 2025 · Oct 14, 2025
diff --git a/_attributes/attributes-microshift.adoc b/_attributes/attributes-microshift.adoc
@@ -13,6 +13,8 @@
 :microshift-short: MicroShift
 //gitops version for 4.17-4.19
 :gitops-ver: 1.16
+:gitops-title: Red{nbsp}Hat OpenShift GitOps
+:gitops-shortname: GitOps
 :product-registry: OpenShift image registry
 :product-version: 4.20
 :rhel-major: rhel-9

diff --git a/microshift_install_rpm_opt/microshift-install-optional-rpms.adoc b/microshift_install_rpm_opt/microshift-install-optional-rpms.adoc
@@ -1,49 +1,30 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="microshift-install-optional-rpms"]
 = Installing optional RPM packages
+
 include::_attributes/attributes-microshift.adoc[]
 :context: microshift-install-optional-rpm
 
 toc::[]
 
-You can install optional RPM packages with {microshift-short} to provide additional node and application services.
+[role="_abstract"]
+When you install {microshift-short}, you can add optional RPM packages to help manage your deployments. Examples of optional RPMs include those designed to expand your network, add and manage Operators, and manage applications. Use the following procedures to add the packages that you need.
 
-[id="microshift-install-rpm-add-ons"]
-== Installing optional packages
+include::modules/microshift-install-rpms-gitops.adoc[leveloffset=+1]
 
-When you install {microshift-short}, optional RPM packages can be added. Examples of optional RPMs include those designed to expand your network, add and manage operators, and manage applications. Use the following procedures to add the packages that you need.
+include::modules/microshift-install-multus-rpm.adoc[leveloffset=+1]
 
-include::modules/microshift-install-rpms-gitops.adoc[leveloffset=+2]
+include::modules/microshift-install-rpms-olm.adoc[leveloffset=+1]
 
-//additional resources for installing GitOps
-[role="_additional-resources"]
-.Additional resources
-* xref:../microshift_running_apps/microshift-gitops.adoc#microshift-gitops[Automating application management with the GitOps controller]
+include::modules/microshift-otel-install.adoc[leveloffset=+1]
 
-include::modules/microshift-install-multus-rpm.adoc[leveloffset=+2]
+include::modules/microshift-rhoai-install.adoc[leveloffset=+1]
 
-//additional resources for installing Multus
+[id="additional-resources_microshift-install-optional-rpms"]
 [role="_additional-resources"]
-.Additional resources
+== Additional resources
+* xref:../microshift_running_apps/microshift-gitops.adoc#microshift-gitops[Automating application management with the {gitops-shortname} controller]
 * xref:../microshift_networking/microshift_multiple_networks/microshift-cni-multus.adoc#microshift-cni-multus[About using multiple networks]
-
-include::modules/microshift-install-rpms-olm.adoc[leveloffset=+2]
-
-//additional resources for installing OLM
-[role="_additional-resources"]
-.Additional resources
 * xref:../microshift_running_apps/microshift_operators/microshift-operators-olm.adoc#microshift-operators-olm[Using Operator Lifecycle Manager with {microshift-short}]
-
-include::modules/microshift-otel-install.adoc[leveloffset=+2]
-
-//additional resources for installing Observability
-[role="_additional-resources"]
-.Additional resources
 * xref:../microshift_running_apps/microshift-observability-service.adoc#microshift-observability-service[Using {microshift-short} Observability]
-
-include::modules/microshift-rhoai-install.adoc[leveloffset=+2]
-
-//additional resources for installing RHOAI
-[role="_additional-resources"]
-.Additional resources
-* xref:../microshift_ai/microshift-rhoai.adoc#microshift-rh-openshift-ai[Using {rhoai} with {microshift-short}]
+* xref:../microshift_ai/microshift-rhoai.adoc#microshift-rh-openshift-ai[Using {rhoai} with {microshift-short}]
diff --git a/microshift_running_apps/microshift-observability-service.adoc b/microshift_running_apps/microshift-observability-service.adoc
@@ -1,17 +1,15 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="microshift-observability-service"]
-= Using {microshift-short} Observability
+= Using MicroShift Observability
 include::_attributes/attributes-microshift.adoc[]
 :context: microshift-observability-service
 
 toc::[]
 
+[role="_abstract"]
 {microshift-short} Observability collects and transmits system data for monitoring and analysis. The data includes performance and usage metrics, and error reporting.
 
 include::modules/microshift-otel-install.adoc[leveloffset=+1]
-[role="_additional-resources"]
-.Additional resources
- * xref:../microshift_install_rpm_opt/microshift-install-optional-rpms.adoc#microshift-install-optional-rpms[Installing optional RPM packages]
 
 include::modules/microshift-otel-config.adoc[leveloffset=+1]
 
@@ -26,6 +24,3 @@ include::modules/microshift-otel-config-medium.adoc[leveloffset=+1]
 include::modules/microshift-otel-config-large.adoc[leveloffset=+1]
 
 include::modules/microshift-otel-verify.adoc[leveloffset=+1]
-
-
-
diff --git a/modules/microshift-install-multus-rpm.adoc b/modules/microshift-install-multus-rpm.adoc
@@ -6,6 +6,7 @@
 [id="microshift-installing-multus_{context}"]
 = Installing the multiple networks plugin
 
+[role="_abstract"]
 You can install the {microshift-short} Multus Container Network Interface (CNI) plugin alongside a new {microshift-short} installation. If you want to attach additional networks to a pod for high-performance network configurations, install the `microshift-multus` RPM package.
 
 [IMPORTANT]
@@ -29,10 +30,7 @@ If you create your custom resources (CRs) while you are completing your installa
 
 .Next steps
 
-. Continue with your new {microshift-short} installation, including any add-ons.
-
-. Create the custom resources (CRs) needed for your {microshift-short} Multus CNI plugin.
-
-. Configure other networking CNIs as needed.
-
-. After you have finished installing all of the RPMs that you want to include, start the {microshift-short} service. The {microshift-short} Multus CNI plugin is automatically deployed.
+* Continue with your new {microshift-short} installation, including any add-ons.
+* Create the custom resources (CRs) needed for your {microshift-short} Multus CNI plugin.
+* Configure other networking CNIs as needed.
+* After you have finished installing all of the RPMs that you want to include, start the {microshift-short} service. The {microshift-short} Multus CNI plugin is automatically deployed.
diff --git a/modules/microshift-install-rpms-gitops.adoc b/modules/microshift-install-rpms-gitops.adoc
@@ -1,16 +1,17 @@
 // Module included in the following assemblies:
 //
-// microshift/microshift-install-rpm.adoc
+// microshift/microshift-install-optional-rpms.adoc
 
 :_mod-docs-content-type: PROCEDURE
 [id="microshift-installing-rpms-for-gitops_{context}"]
-= Installing the GitOps Argo CD manifests from an RPM package
+= Installing the {gitops-shortname} Argo CD manifests from an RPM package
 
-You can use a lightweight version of OpenShift GitOps with {microshift-short} to help manage your applications by installing the `microshift-gitops` RPM package. The `microshift-gitops` RPM package includes the necessary manifests to run core Argo CD.
+[role="_abstract"]
+You can use a lightweight version of {gitops-title} with {microshift-short} to help manage your applications by installing the `microshift-gitops` RPM package. You can consistently configure and deploy Kubernetes-based infrastructure and applications across node and development lifecycles by using the declarative {gitops-shortname} engine. The `microshift-gitops` RPM package includes the necessary manifests to run core Argo CD.
 
 [IMPORTANT]
 ====
-The Argo CD CLI is not available on {microshift-short}. This process installs basic GitOps functions.
+The Argo CD CLI is not available on {microshift-short}. This process installs basic {gitops-shortname} functions.
 ====
 
 .Prerequisites
@@ -20,14 +21,14 @@ The Argo CD CLI is not available on {microshift-short}. This process installs ba
 
 .Procedure
 
-. Enable the GitOps repository with the subscription manager by running the following command:
+. Enable the {gitops-shortname} repository with the subscription manager by running the following command:
 +
 [source,terminal,subs="attributes+"]
 ----
 $ sudo subscription-manager repos --enable=gitops-{gitops-ver}-for-{rhel-major}-$(uname -m)-rpms
 ----
 
-. Install the {microshift-short} GitOps package by running the following command:
+. Install the {microshift-short} {gitops-shortname} package by running the following command:
 +
 [source,terminal]
 ----

diff --git a/modules/microshift-install-rpms-olm.adoc b/modules/microshift-install-rpms-olm.adoc
@@ -6,7 +6,8 @@
 [id="microshift-installing-with-olm-from-rpm-package_{context}"]
 = Installing the Operator Lifecycle Manager (OLM) from an RPM package
 
-When you install {microshift-short}, the Operator Lifecycle Manager (OLM) package is not installed by default. You can install the OLM on your {microshift-short} instance by using an RPM package.
+[role="_abstract"]
+When you install {microshift-short}, the Operator Lifecycle Manager (OLM) package is not installed by default. You can install the OLM on your {microshift-short} instance by using an RPM package. OLM helps you install, update, and manage the lifecycle of Kubernetes native applications (Operators) and their associated services running in each {microshift-short} node.
 
 .Procedure
 
@@ -22,4 +23,4 @@ $ sudo dnf install microshift-olm
 [source,terminal]
 ----
 $ sudo systemctl restart microshift
-----
+----
diff --git a/modules/microshift-otel-config-examples.adoc b/modules/microshift-otel-config-examples.adoc
@@ -6,6 +6,7 @@
 [id="microshift-otel-config-examples_{context}"]
 = Selecting a {microshift-short} Observability configuration
 
+[role="_abstract"]
 The amount and complexity of the data depends on predefined configurations. These configurations determine the number of data sources and the amount of collected data that is transmitted. These configurations are defined as small, medium, and large (default).
 
 The `opentelemetry-collector.yaml` file includes specific parameters that are used to collect data for monitoring the system resources. All warnings for node events are included in the collected data. {microshift-short} Observability collects and transmits data for the following resources:

diff --git a/modules/microshift-otel-config-large.adoc b/modules/microshift-otel-config-large.adoc
@@ -6,6 +6,7 @@
 [id="microshift-otel-config-large_{context}"]
 = Selecting a large configuration
 
+[role="_abstract"]
 You can configure {microshift-short} Observability to collect the maximum amount of performance and resource information, from the maximum number of sources, by updating the YAML file.
 
 .Procedure

diff --git a/modules/microshift-otel-config-medium.adoc b/modules/microshift-otel-config-medium.adoc
@@ -6,6 +6,7 @@
 [id="microshift-otel-config-medium_{context}"]
 = Selecting a medium configuration
 
+[role="_abstract"]
 You can configure {microshift-short} Observability to collect performance and resource information from various sources by updating the YAML file.
 
 .Procedure
@@ -71,7 +72,7 @@ service:
               otlp:
                 protocol: http/protobuf
                 endpoint: http://${env:OTEL_BACKEND}:4318 <2>
-----                
+----
 <1> Replace the variable `${env:OTEL_BACKEND}` with the IP address or hostname of the remote back end. This IP address resolves to the local node's hostname. Any unreachable endpoint is reported in the `microshift-observability` service logs.
 <2> Replace the variable `${env:OTEL_BACKEND}` with the IP address or hostname of the remote back end. This IP address resolves to the local node's hostname. Any unreachable endpoint is reported in the `microshift-observability` service logs.
 

diff --git a/modules/microshift-otel-config-small.adoc b/modules/microshift-otel-config-small.adoc
@@ -6,6 +6,7 @@
 [id="microshift-otel-config-small_{context}"]
 = Selecting a small configuration
 
+[role="_abstract"]
 You can configure {microshift-short} Observability to collect the smallest amount of performance and resource information from various sources by updating the YAML file.
 
 .Procedure

diff --git a/modules/microshift-otel-config.adoc b/modules/microshift-otel-config.adoc
@@ -6,9 +6,8 @@
 [id="microshift-otel-config_{context}"]
 = Configuring {microshift-short} Observability
 
-You must configure {microshift-short} Observability after it is installed by specifying a valid endpoint. If an endpoint is not specified, {microshift-short} Observability does not start.
-
-You can specify any OpenTelemetry Protocol (OTLP)-compatible endpoint for each configuration before starting {microshift-short}. 
+[role="_abstract"]
+You must configure {microshift-short} Observability after it is installed by specifying a valid endpoint. If an endpoint is not specified, {microshift-short} Observability does not start. You can specify any OpenTelemetry Protocol (OTLP)-compatible endpoint for each configuration before starting {microshift-short}.
 
 .Procedure
 
@@ -36,10 +35,10 @@ service:
               otlp:
                 protocol: http/protobuf
                 endpoint: http://${env:OTEL_BACKEND}:4318 <2>
-# ...                
-----  
+# ...
+----
 <1> Replace `${env:OTEL_BACKEND}` with the IP address or hostname of the remote back end. This IP address resolves to the local node's hostname. An unreachable endpoint is reported in the {microshift-short} service logs.
-<2> Replace `${env:OTEL_BACKEND}` with the IP address or hostname of the remote back end. This IP address resolves to the local node's hostname. An unreachable endpoint is reported in the {microshift-short} service logs.    
+<2> Replace `${env:OTEL_BACKEND}` with the IP address or hostname of the remote back end. This IP address resolves to the local node's hostname. An unreachable endpoint is reported in the {microshift-short} service logs.
 
 . Each time that you update the `opentelemetry-collector.yaml` file, you must restart {microshift-short} Observability to apply the updates.
 +

diff --git a/modules/microshift-otel-install.adoc b/modules/microshift-otel-install.adoc
@@ -6,7 +6,8 @@
 [id="microshift-otel-install_{context}"]
 = Installing and enabling {microshift-short} Observability
 
-You can install {microshift-short} Observability at any time, including during the initial {microshift-short} installation.
+[role="_abstract"]
+You can install {microshift-short} Observability at any time, including during the initial {microshift-short} installation. Observability collects and transmits system data for monitoring and analysis, such as performance and usage metrics and error reporting.
 
 .Procedure
 . Install the `microshift-observability` RPM by entering the following command:
@@ -38,4 +39,3 @@ $ sudo systemctl restart microshift-observability
 ----
 
 The installation is successful if there is no output after you start the `microshift-observability` RPM.
-
diff --git a/modules/microshift-otel-verify.adoc b/modules/microshift-otel-verify.adoc
@@ -6,6 +6,7 @@
 [id="microshift-otel-verify_{context}"]
 = Verifying the {microshift-short} Observability state
 
+[role="_abstract"]
 After {microshift-short} Observability starts, you can verify the state by using a `systemd` service. The {microshift-short} Observability service logs are available as `journald` logs.
 
 .Procedure
@@ -23,4 +24,3 @@ $ sudo systemctl status microshift-observability
 ----
 $ sudo journalctl -u microshift-observability
 ----
-
diff --git a/modules/microshift-rhoai-install.adoc b/modules/microshift-rhoai-install.adoc
@@ -6,16 +6,17 @@
 [id="microshift-rhoai-install_{context}"]
 = Installing the {rhoai-full} RPM
 
-To use AI models in {microshift-short} deployments, use this procedure to install the {rhoai-full} ({rhoai}) RPM with a new {microshift-short} installation. You can also install the RPM on an existing {microshift-short} instance if you restart the system.
+[role="_abstract"]
+To use AI models in {microshift-short} deployments, install the {rhoai-full} ({rhoai}) RPM with a new {microshift-short} installation. You can also install the RPM on an existing {microshift-short} instance if you restart the system.
+
+[NOTE]
+====
+The `microshift-ai-model-serving` RPM contains manifests that deploy `kserve`, with the raw deployment mode enabled, and `ServingRuntimes` objects in the `redhat-ods-applications` namespace.
+====
 
 :FeatureName: {rhoai-full}
 include::snippets/technology-preview.adoc[leveloffset=+1]
 
-//[IMPORTANT]
-//====
-//Installing the `microshift-ai-model-serving` RPM before running the `$ systemctl start microshift` command for the first time can cause {microshift-short} to fail to start. However, {microshift-short} automatically restarts successfully in this case.
-//====
-
 .Prerequisites
 
 * The system requirements for installing {microshift-short} have been met.
@@ -26,11 +27,6 @@ include::snippets/technology-preview.adoc[leveloffset=+1]
 * You configured the required accelerators, hardware, operating system, and {microshift-short} to provide the resources your model needs.
 * Your AI model is ready to use.
 
-[NOTE]
-====
-The `microshift-ai-model-serving` RPM contains manifests that deploy `kserve`, with the raw deployment mode enabled, and `ServingRuntimes` objects in the `redhat-ods-applications` namespace.
-====
-
 .Procedure
 
 . Install the {microshift-short} AI-model-serving RPM package by running the following command:
@@ -51,9 +47,13 @@ $ sudo systemctl restart microshift
 +
 [source,terminal]
 ----
-$ sudo dnf install microshift-ai-model-serving-release-info <1>
+$ sudo dnf install microshift-ai-model-serving-release-info
 ----
-<1> The release information package contains a JSON file with image references useful for offline procedures or deploying copy of a `ServingRuntime` to your namespace during a bootc image build.
++
+[NOTE]
+====
+The `microshift-ai-model-serving-release-info` RPM contains a JSON file with image references useful for offline procedures or deploying a copy of a `ServingRuntime` Custom Resource to your namespace during a bootc image build.
+====
 
 .Verification