📖 a few documentation touch-ups (#1351)

Signed-off-by: Per Goncalves da Silva <pegoncal@redhat.com>
Co-authored-by: Per Goncalves da Silva <pegoncal@redhat.com>

docs/index.md

@@ -3,43 +3,37 @@ hide:
   - toc
 ---
 
-# Overview
+# Operator Lifecycle Manager
 
-Operator Lifecycle Manager (OLM) is an open-source [CNCF](https://www.cncf.io/) project with the mission to manage the
-lifecycle of cluster extensions centrally and declaratively on Kubernetes clusters. Its purpose is to make installing,
-running, and updating functional extensions to the cluster easy, safe, and reproducible for cluster administrators and PaaS administrators.
+The Operator Lifecycle Manager (OLM) is an open-source project under the [Cloud Native Computing Foundation (CNCF)](https://www.cncf.io/), designed to simplify and centralize the management of Kubernetes cluster extensions. OLM streamlines the process of installing, running, and updating these extensions, making it easier, safer, and more reproducible for cluster and platform administrators alike.
 
-Previously, OLM was focused on a particular type of cluster extension: [Operators](https://operatorhub.io/what-is-an-operator#:~:text=is%20an%20Operator-,What%20is%20an%20Operator%20after%20all%3F,or%20automation%20software%20like%20Ansible.).
-Operators are a method of packaging, deploying, and managing a Kubernetes application. An Operator is composed of one or more controllers paired with one or both of the following objects:
+Originally, OLM was focused on managing a specific type of extension known as [Operators](https://operatorhub.io/what-is-an-operator#:~:text=is%20an%20Operator-,What%20is%20an%20Operator%20after%20all%3F,or%20automation%20software%20like%20Ansible.), which are powerful tools that automate the management of complex Kubernetes applications. At its core, an Operator is made up of controllers that automate the lifecycle of applications, paired with:
 
-* One or more API extensions
-* One or more [CustomResourceDefinitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) (CRDs).
+- One or more Kubernetes API extensions.
+- One or more [CustomResourceDefinitions (CRDs)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/), allowing administrators to define custom resources.
 
-OLM helped define lifecycles for these extensions: from packaging and distribution to installation, configuration, upgrade, and removal.
+The purpose of OLM is to manage the lifecycle of these extensions—from their packaging and distribution to installation, updates, and eventual removal—helping administrators ensure stability and security across their clusters.
 
-The first iteration of OLM, termed OLM v0, included several concepts and features targeting the stability, security, and supportability of the life-cycled applications, for instance:
+In its first release (OLM v0), the project introduced several important concepts and features aimed at improving the lifecycle management of Kubernetes applications:
 
-* A dependency model that enabled cluster extensions to focus on their primary purpose by delegating out of scope behavior to dependencies
-* A constraint model that allowed cluster extension developers to define support limitations such as conflicting extensions, and minimum kubernetes versions
-* A namespace-based multi-tenancy model in lieu of namespace-scoped CRDs
-* A packaging model in which catalogs of extensions, usually containing the entire version history of each extension, are made available to clusters for cluster users to browse and select from
+- **Dependency Model**: Enables extensions to focus on their primary function by delegating non-essential tasks to other dependencies.
+- **Constraint Model**: Allows developers to define compatibility constraints such as conflicting extensions or minimum required Kubernetes versions.
+- **Namespace-Based Multi-Tenancy**: Provides a multi-tenancy model to manage multiple extensions without the need for namespace-scoped CRDs.
+- **Packaging Model**: Distributes extensions through catalogs, allowing users to browse and install extensions, often with access to the full version history.
 
-Since its initial release, OLM has helped catalyse the growth of Operators throughout the Kubernetes ecosystem. [OperatorHub.io](https://operatorhub.io/)
-is a popular destination for discovering Operators, and boasts over 300 packages from many different vendors.
+Thanks to these innovations, OLM has played a significant role in popularizing Operators throughout the Kubernetes ecosystem. A prime example of its impact is [OperatorHub.io](https://operatorhub.io/), a widely-used platform with over 300 Operators from various vendors, providing users with a central location to discover and install Operators.
 
-## Why are we building OLM v1?
+## Why Build OLM v1?
 
-The Operator Lifecycle Manager (OLM) has been in production for over five years, serving as a critical component in managing Kubernetes Operators.
-Over this time, the community has gathered valuable insights from real-world usage, identifying both the strengths and limitations of the initial design,
-and validating the design's initial assumptions. This process led to a complete redesign and rewrite of OLM that, compared to its predecessor, aims to
-provide:
+After five years of real-world use, OLM has become an essential part of managing Kubernetes Operators. However, over time, the community has gathered valuable insights, uncovering both the strengths and limitations of OLM v0. These findings have led to a comprehensive redesign and the creation of OLM v1, with several key improvements over the initial version:
 
-* A simpler API surface and mental model
-* Less opinionated automation and greater flexibility
-* Support for Kubernetes applications beyond only Operators
-* Security by default
-* Helm Chart support
-* GitOps support
+- **Simpler API and Mental Model**: Streamlined APIs and a more intuitive design, making it easier to understand and work with.
+- **Greater Flexibility**: Less rigid automation, allowing for more customization and broader use cases.
+- **Beyond Operators**: Support for a wider range of Kubernetes applications, not limited to Operators.
+- **Security by Default**: Enhanced security features out-of-the-box, reducing vulnerabilities.
+- **Helm Chart and GitOps Support**: Expanded support for popular Kubernetes tools like Helm and GitOps, broadening the range of integration options.
 
-To learn more about where v1 one came from, and where it's going, please see [Multi-Tenancy Challenges, Lessons Learned, and Design Shifts](project/olmv1_design_decisions.md)
-and our feature [Roadmap](project/olmv1_roadmap.md).
+For more details on the evolution of OLM and the roadmap for v1, explore the following resources:
+
+- [Multi-Tenancy Challenges, Lessons Learned, and Design Shifts](project/olmv1_design_decisions.md)
+- [OLM v1 Roadmap](project/olmv1_roadmap.md)

docs/project/olmv1_architecture.md

@@ -3,16 +3,16 @@ hide:
   - toc
 ---
 
-# OLM V1 Architecture
+## OLM v1 Architecture
 
-This document describes the OLM v1 architecture. OLM v1 consists of two main components:
+This document provides an overview of the architecture of OLM v1, which consists of two primary components:
 
-* [operator-controller](https://github.com/operator-framework/operator-controller)
-* [catalogD](https://github.com/operator-framework/catalogd)
+1. [operator-controller](https://github.com/operator-framework/operator-controller)
+2. [catalogD](https://github.com/operator-framework/catalogd)
 
-The diagram below illustrates the OLM v1 architecture and its components,  and the following sections describe each of the components in detail.
+The diagram below visually represents the architecture of OLM v1, followed by descriptions of each component and its role within the system.
 
-### Diagram
+### Architecture Diagram
 
 ```mermaid
 flowchart TB
@@ -53,39 +53,48 @@ flowchart TB
     A -- pushed to --> B
 ```
 
-**Note**: The direction of the arrow indicates the active part of communication i.e. if arrow starts from A and points to B that means A consumes the information from B unless specifically mentioned.
+**Note**: The direction of the arrows represents the flow of communication. If an arrow starts from A and points to B, it indicates that A retrieves or consumes information from B, unless otherwise specified.
 
-### Operator-controller:
+---
+
+### operator-controller
+
+The `operator-controller` is the core component of OLM v1. Its responsibilities include:
 
-operator-controller is the central component of OLM v1. It is responsible:
+- Managing a cache of catalog metadata provided by catalogD through its HTTP server.
+- Ensuring the catalog metadata cache is kept up-to-date with the latest catalog state.
+- Identifying the appropriate `registry+v1` bundle that meets the constraints defined in the `ClusterExtension` resource (e.g., package name, version, channel) based on the cluster's current state.
+- Unpacking and applying bundle manifests (e.g., installing or updating the operator).
 
- * managing a cache of catalog metadata provided by catalogd through its HTTP server
- * keeping the catalog metadata cache up-to-date with the current state of the catalogs
- * locating the right `registry+v1` bundle, if any,  that meet the constraints expressed in the `ClusterExtension` resource, such as package name, version range, channel, etc. given the current state of the cluster
- * unpacking the bundle
- * applying the bundle manifests: installing or updating the content.
-
- It has three main sub-components:
+The operator-controller has three key sub-components:
 
- * Cluster Extension Controller: 
-    * Queries the catalogd (catalogd HTTP Server) to get catalog information.
-    * Once received the catalog information is saved  to catalog-cache. The cache will be updated automatically if a Catalog is noticed to have a different resolved image reference. 
-    * Reaches out to the registry to download the bundle container images, saves it to the bundle cache,  unpacks it and applies the bundle manifests to the cluster.  
-    * It is also Responsible for figuring out which bundle to upgrade
- * Resolver:
-    * Helps the cluster extension controller to filter the bundle reference after applying the user restrictions (e.g. name, priority etc) and returns the bundle reference to the extension controller.
- * Bundle Cache:
-    * Bundle cache returns the cache for the bundle. If a cache does not already exist, a new one will be created.
+1. **Cluster Extension Controller**:
+    - Queries catalogD (via its HTTP server) to retrieve catalog information.
+    - Saves catalog information in the catalog cache and automatically updates the cache if a catalog has a new image reference.
+    - Downloads bundle container images from the registry, saves them to the bundle cache, unpacks them, and applies the bundle manifests to the cluster.
+    - Handles bundle upgrades by determining which bundle is the correct one to apply.
 
-### Catalogd:
+2. **Resolver**:
+    - Assists the Cluster Extension Controller by filtering bundle references according to user-defined restrictions (e.g., package name, priority). It returns the filtered bundle reference to the extension controller.
+
+3. **Bundle Cache**:
+    - Stores previously unpacked bundles. If a bundle is not already cached, it downloads and caches it for future use.
+
+---
 
-Catalogd unpacks [file-based catalog (FBC)](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs) content that is packaged and shipped in container images, for consumption by clients on-clusters (unpacking from other sources, like git repos, OCI artifacts etc, are in the roadmap for catalogD). It serves the extension metadata, provided by the extension authors, found in the FBC, making it possible for on-cluster clients to discover installable content.
+### catalogd
 
-* Catalogd can be broken down in to three sub-components i.e. ClusterCatalog controller, catalogd http server, catalogd content cache.
-* Catalog controller  is responsible for pulling FBC based catalog images from registry and unpacking them into the catalog content cache. It is also responsible for reconciling the latest changes in the cluster catalog.
-* Catalogd http server is responsible for serving catalog information to clients e.g. cluster extension controller.
-* Catalogd content cache is maintained by the catalog controller and used by the catalogd http server to answer queries from clients.
+catalogd is responsible for unpacking [file-based catalog (FBC)](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs) content, which is packaged and delivered as container images. It allows on-cluster clients to discover installable content by providing access to this metadata. In the future, catalogD will also support other sources like Git repositories and OCI artifacts.
 
+catalogd has three main sub-components:
 
+1. **ClusterCatalog Controller**:
+    - Pulls FBC-based catalog images from the registry and unpacks them into the catalog content cache.
+    - Reconciles any changes in the catalog and ensures the latest content is reflected in the cluster.
+
+2. **CatalogD HTTP Server**:
+    - Serves catalog information to clients, such as the Cluster Extension Controller.
 
+3. **CatalogD Content Cache**:
+    - A cache maintained by the Catalog Controller that stores unpacked catalog data, which the CatalogD HTTP Server uses to respond to client queries.
 

docs/project/olmv1_limitations.md

@@ -3,23 +3,22 @@ hide:
   - toc
 ---
 
-## OLM v0 Extension Support
+## Content Support
 
-Currently, OLM v1 supports installing cluster extensions that meet the following criteria:
-
-* The extension must support installation via the `AllNamespaces` install mode.
-* The extension must not use webhooks.
-* The extension must not declare dependencies using any of the following file-based catalog properties:
+Currently, OLM v1 only supports installing operators packaged in [OLM v0 bundles](https://olm.operatorframework.io/docs/tasks/creating-operator-bundle/)
+, also known as `registry+v1` bundles. Additionally, the bundled operator, or cluster extension:
 
+* **must** support installation via the `AllNamespaces` install mode.
+* **must not** use webhooks.
+* **must not** declare dependencies using any of the following file-based catalog properties:
     * `olm.gvk.required`
     * `olm.package.required`
     * `olm.constraint`
 
-When you install an extension, OLM v1 validates that the bundle you want to install meets these constraints. If you try to install an extension that does not meet these constraints, an error message is printed in the cluster extension's conditions.
+OLM v1 verifies these criteria at install time and will surface violations in the `ClusterExtensions`'s `.status.conditions`.
 
 !!! important
 
     OLM v1 does not support the `OperatorConditions` API introduced in legacy OLM.
 
-    Currently, there is no testing to validate against this constraint. If an extension uses the `OperatorConditions` API, the extension does not install correctly. Most extensions that rely on this API fail at start time, but some might fail during reconcilation. 
-
+    Currently, there is no testing to validate against this constraint. If an extension uses the `OperatorConditions` API, the extension does not install correctly. Most extensions that rely on this API fail at start time, but some might fail during reconcilation.

docs/project/olmv1_roadmap.md

@@ -153,7 +153,3 @@ OLM 1.0 does not support managing bundles or extension versions that do not supp
 - Migration scripting is provided to mass-convert existing installed extensions (“Subscription” / “OperatorGroup” objects) on existing clusters to the new OLM 1.0 model assuming they are compatible
 
 - Extension authors that are also SRE/Managed PaaS administrators are incentivized to make their extension compatible with the requirements of OLM 1.0 to reap the operational benefits
-
-# TODO
-- Definition of "extension"
-- Does OLM become ELM?  Does this provide of provisioning bundles that do not add APIs?