📖 Content organization (#1324)

* organize docs

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

* First stab at doc hierarchy

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

---------

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

CONTRIBUTING.md

@@ -7,15 +7,16 @@ Operator Controller is an Apache 2.0 licensed project and accepts contributions
 By contributing to this project you agree to the Developer Certificate of
 Origin (DCO). This document was created by the Linux Kernel community and is a
 simple statement that you, as a contributor, have the legal right to make the
-contribution. See the [DCO](DCO) file for details.
+contribution. See the [DCO](https://github.com/operator-framework/operator-controller/blob/main/DCO) file for details.
 
 ## Overview
 
 Thank you for your interest in contributing to the Operator-Controller.
 
-As you may or may not know, the Operator-Controller project aims to deliver the user experience described in the [Operator Lifecycle Manager (OLM) V1 Product Requirements Document (PRD)](https://docs.google.com/document/d/1-vsZ2dAODNfoHb7Nf0fbYeKDF7DUqEzS9HqgeMCvbDs/edit). The design requirements captured in the OLM V1 PRD were born from customer and community feedback based on the experience they had with the released version of [OLM V0](github.com/operator-framework/operator-lifecycle-manager).
+As you may or may not know, the Operator-Controller project aims to deliver the user experience described in the [Operator Lifecycle Manager (OLM) V1 Product Requirements Document (PRD)](https://docs.google.com/document/d/1-vsZ2dAODNfoHb7Nf0fbYeKDF7DUqEzS9HqgeMCvbDs/edit). The design requirements captured in the OLM V1 PRD were born from customer and community feedback based on the experience they had with the released version of [OLM V0](https://github.com/operator-framework/operator-lifecycle-manager).
 
 The user experience captured in the OLM V1 PRD introduces many requirements that are best satisfied by a microservices architecture. The OLM V1 experience currently relies on two projects:
+
 - [The Operator-Controller project](https://github.com/operator-framework/operator-controller/), which is the top level component allowing users to specify operators they'd like to install.
 - [The Catalogd project](https://github.com/operator-framework/catalogd/), which hosts operator content and helps users discover installable content.
 
@@ -45,14 +46,15 @@ Please keep this workflow in mind as you read through the document.
 ## How are Milestones Designed?
 
 It's unreasonable to attempt to consider all of the design requirements laid out in the [OLM V1 PRD](https://docs.google.com/document/d/1-vsZ2dAODNfoHb7Nf0fbYeKDF7DUqEzS9HqgeMCvbDs/edit) from the onset of the project. Instead, the community attempts to design Milestones with the following principles:
+
 - Milestones are tightly scoped units of work, ideally lasting one to three weeks.
 - Milestones are derived from the OLM V1 PRD.
 - Milestones are "demo driven", meaning that a set of acceptance criteria is defined upfront and the milestone is done as soon as some member of the community can run the demo.
 - Edge cases found during development are captured in issues and assigned to the GA Milestone, which contains a list of issues that block the release of operator-controller v1.0.0 .
 
 This "demo driven" development model will allow us to collect user experience and regularly course correct based on user feedback. Subsequent milestone may revert features or change the user experience based on community feedback.
 
-The project maintainer will create a [GitHub Discussion](github.com/operator-framework/operator-controller/discussions) for the upcoming milestone once we've finalized the current milestone. Please feel encouraged to contribute suggestions for the milestone in the discussion.
+The project maintainer will create a [GitHub Discussion](https://github.com/operator-framework/operator-controller/discussions) for the upcoming milestone once we've finalized the current milestone. Please feel encouraged to contribute suggestions for the milestone in the discussion.
 
 ## Where are Operator Controller Milestones?
 
@@ -67,6 +69,7 @@ As discussed earlier, the operator-controller adheres to a microservice architec
 ## Submitting Issues
 
 Unsure where to submit an issue? 
+
 - [The Operator-Controller project](https://github.com/operator-framework/operator-controller/), which is the top level component allowing users to specify operators they'd like to install.
 - [The Catalogd project](https://github.com/operator-framework/catalogd/), which hosts operator content and helps users discover installable content.
 
@@ -87,7 +90,7 @@ approach of changes.
 When contributing changes that require a new dependency, check whether it's feasible to directly vendor that
 code [without introducing a new dependency](https://go-proverbs.github.io/).
 
-Currently, PRs require at least one approval from a operator-controller maintainer in order to get merged.
+Currently, PRs require at least one approval from an operator-controller maintainer in order to get merged.
 
 ### Code style
 

Makefile

@@ -312,17 +312,18 @@ quickstart: $(KUSTOMIZE) manifests #EXHELP Generate the installation release man
 OPERATOR_CONTROLLER_API_REFERENCE_FILENAME := operator-controller-api-reference.md
 CATALOGD_API_REFERENCE_FILENAME := catalogd-api-reference.md
 CATALOGD_TMP_DIR := $(ROOT_DIR)/.catalogd-tmp/
+API_REFERENCE_DIR := $(ROOT_DIR)/docs/api-reference
 crd-ref-docs: $(CRD_REF_DOCS) #EXHELP Generate the API Reference Documents.
-	rm -f $(ROOT_DIR)/docs/refs/api/$(OPERATOR_CONTROLLER_API_REFERENCE_FILENAME)
+	rm -f $(API_REFERENCE_DIR)/$(OPERATOR_CONTROLLER_API_REFERENCE_FILENAME)
 	$(CRD_REF_DOCS) --source-path=$(ROOT_DIR)/api \
-	--config=$(ROOT_DIR)/docs/refs/api/crd-ref-docs-gen-config.yaml \
-	--renderer=markdown --output-path=$(ROOT_DIR)/docs/refs/api/$(OPERATOR_CONTROLLER_API_REFERENCE_FILENAME);
+	--config=$(API_REFERENCE_DIR)/crd-ref-docs-gen-config.yaml \
+	--renderer=markdown --output-path=$(API_REFERENCE_DIR)/$(OPERATOR_CONTROLLER_API_REFERENCE_FILENAME);
 	rm -rf $(CATALOGD_TMP_DIR)
 	git clone --depth 1 --branch $(CATALOGD_VERSION) https://github.com/operator-framework/catalogd $(CATALOGD_TMP_DIR)
-	rm -f $(ROOT_DIR)/docs/refs/api/$(CATALOGD_API_REFERENCE_FILENAME)
+	rm -f $(API_REFERENCE_DIR)/$(CATALOGD_API_REFERENCE_FILENAME)
 	$(CRD_REF_DOCS) --source-path=$(CATALOGD_TMP_DIR)/api \
-	--config=$(ROOT_DIR)/docs/refs/api/crd-ref-docs-gen-config.yaml \
-	--renderer=markdown --output-path=$(ROOT_DIR)/docs/refs/api/$(CATALOGD_API_REFERENCE_FILENAME)
+	--config=$(API_REFERENCE_DIR)/crd-ref-docs-gen-config.yaml \
+	--renderer=markdown --output-path=$(API_REFERENCE_DIR)/$(CATALOGD_API_REFERENCE_FILENAME)
 	rm -rf $(CATALOGD_TMP_DIR)/
 
 VENVDIR := $(abspath docs/.venv)

README.md

@@ -2,137 +2,25 @@
 The operator-controller is the central component of Operator Lifecycle Manager (OLM) v1.
 It extends Kubernetes with an API through which users can install extensions.
 
-## Mission
+## Overview
+
+OLM v1 is the follow-up to [OLM v0](https://github.com/operator-framework/operator-lifecycle-manager). Its purpose is to provide APIs, 
+controllers, and tooling that support the packaging, distribution, and lifecycling of Kubernetes extensions. It aims to:
 
-OLM’s purpose is to provide APIs, controllers, and tooling that support the packaging, distribution, and lifecycling of Kubernetes extensions. It aims to:
 - align with Kubernetes designs and user assumptions
 - provide secure, high-quality, and predictable user experiences centered around declarative GitOps concepts
 - give cluster admins the minimal necessary controls to build their desired cluster architectures and to have ultimate control
 
-## Overview
-
-OLM v1 is the follow-up to OLM v0, located [here](https://github.com/operator-framework/operator-lifecycle-manager).
-
 OLM v1 consists of two different components:
+
 * operator-controller (this repository)
 * [catalogd](https://github.com/operator-framework/catalogd)
 
-For a more complete overview of OLM v1 and how it differs from OLM v0, see our [overview](docs/olmv1_overview.md).
-
-### Installation
-
-The following script will install OLMv1 on a Kubernetes cluster. If you don't have one, you can deploy a Kubernetes cluster with [KIND](https://sigs.k8s.io/kind).
-
-> [!CAUTION]  
-> Operator-Controller depends on [cert-manager](https://cert-manager.io/). Running the following command
-> may affect an existing installation of cert-manager and cause cluster instability.
-
-The latest version of Operator Controller can be installed with the following command:
-
-```bash
-curl -L -s https://github.com/operator-framework/operator-controller/releases/latest/download/install.sh | bash -s
-```
-
-## Getting Started with OLM v1
-
-This quickstart procedure will guide you through the following processes:
-* Deploying a catalog
-* Installing, upgrading, or downgrading an extension
-* Deleting catalogs and extensions
-
-### Create a Catalog
-
-OLM v1 is designed to source content from an on-cluster catalog in the file-based catalog ([FBC](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs)) format.
-These catalogs are deployed and configured through the `ClusterCatalog` resource. More information on adding catalogs
-can be found [here](./docs/Tasks/adding-a-catalog).
-
-The following example uses the official [OperatorHub](https://operatorhub.io) catalog that contains many different
-extensions to choose from. Note that this catalog contains packages designed to work with OLM v0, and that not all packages
-will work with OLM v1. More information on catalog exploration and content compatibility can be found [here](./docs/refs/catalog-queries.md). 
-
-To create the catalog, run the following command:
-
-```bash
-# Create ClusterCatalog
-kubectl apply -f - <<EOF
-apiVersion: catalogd.operatorframework.io/v1alpha1
-kind: ClusterCatalog
-metadata:
-  name: operatorhubio
-spec:
-  source:
-    type: image
-    image:
-      ref: quay.io/operatorhubio/catalog:latest
-      pollInterval: 10m
-EOF
-```
-
-Once the catalog is unpacked successfully, its content will be available for installation.
-
-```bash
-# Wait for the ClusterCatalog to be unpacked
-kubectl wait --for=condition=Unpacked=True clustercatalog/operatorhubio --timeout=60s
-```
-
-### Install a Cluster Extension
-
-For simplicity, the following example manifest includes all necessary resources to install the ArgoCD operator. 
-The manifest includes installation namespace, installer service account and associated minimal set of RBAC permissions 
-needed for installation, and the ClusterExtension resource, which specifies the name and version of the extension to install.
-More information on installing extensions can be found [here](docs/Tasks/installing-an-extension).
-
-```bash
-# Apply the sample ClusterExtension. Manifest already includes
-# namespace and adequately privileged service account
-kubectl apply -f https://raw.githubusercontent.com/operator-framework/operator-controller/main/config/samples/olm_v1alpha1_clusterextension.yaml
-```
-
-### Upgrade the Cluster Extension
-
-To upgrade the installed extension, update the version field in the ClusterExtension resource. Note that
-there must be CRD compatibility between the versions being upgraded, and the target version must be
-compatible with OLM v1. More information on CRD upgrade safety can be found [here](./docs/refs/crd-upgrade-safety.md), 
-compatible with OLM v1. More information on CRD upgrade safety can be found [here](./docs/refs/crd-upgrade-safety.md), 
-and on the extension upgrade process [here](./docs/drafts/Tasks/upgrading-an-extension).
-
-```bash
-# Update to v0.11.0
-kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.11.0"}}}}'
-
-```
-
-For information on the downgrade process, see [here](docs/drafts/downgrading-an-extension.md).
-
-### Uninstall the Cluster Extension
-
-To uninstall an extension, delete the ClusterExtension resource. This will trigger the uninstallation process, which will
-remove all resources created by the extension. More information on uninstalling extensions can be found [here](./docs/Tasks/uninstalling-an-extension).
-
-```bash
-# Delete cluster extension and residing namespace
-kubectl delete clusterextension/argocd
-```
-
-#### Cleanup
-
-Extension installation requires the creation of a namespace, an installer service account, and its RBAC. Once the
-extension is uninstalled, these resources can be cleaned up.
-
-```bash
-# Delete namespace, and by extension, the installer service account, Role, and RoleBinding
-kubectl delete namespace argocd
-```
+For a more complete overview of OLM v1 and how it differs from OLM v0, see our [overview](docs/project/olmv1_design_decisions.md).
 
-```bash
-# Delete installer service account cluster roles
-kubectl delete clusterrole argocd-installer-clusterrole && kubectl delete clusterrole argocd-rbac-clusterrole
-```
+## Getting Started
 
-```bash
-# Delete installer service account cluster role bindings
-kuebctl delete clusterrolebinding argocd-installer-binding && kubectl delete clusterrolebinding argocd-rbac-binding
-```
+To get started with OLM v1, please see our [Getting Started](docs/getting-started/olmv1_getting_started.md) documentation.
 
 ## License
 

docs/drafts/controlling-catalog-selection.md → docs/concepts/controlling-catalog-selection.md

@@ -27,7 +27,7 @@ spec:
   catalog:
     selector:
       matchLabels:
-        olm.operatorframework.io/metadata.name: my-catalog
+        olm.operatorframework.io/metadata.name: my-content-management
 ```
 
 In this example, only the catalog named `my-catalog` will be considered when resolving `my-package`.
@@ -93,7 +93,7 @@ spec:
         - key: olm.operatorframework.io/metadata.name
           operator: NotIn
           values:
-            - unwanted-catalog
+            - unwanted-content-management
 ```
 
 This excludes the catalog named `unwanted-catalog` from consideration.
@@ -134,7 +134,7 @@ spec:
   source:
     type: image
     image:
-      ref: quay.io/example/high-priority-catalog:latest
+      ref: quay.io/example/high-priority-content-management:latest
 ```
 
 Catalogs have a default priority of `0`. The priority can be any 32-bit integer. Catalogs with higher priority values are preferred during bundle resolution.
@@ -171,7 +171,7 @@ If the system cannot resolve to a single bundle due to ambiguity, it will genera
      source:
        type: image
        image:
-         ref: quay.io/example/catalog-a:latest
+         ref: quay.io/example/content-management-a:latest
    ```
 
    ```yaml
@@ -186,7 +186,7 @@ If the system cannot resolve to a single bundle due to ambiguity, it will genera
      source:
        type: image
        image:
-         ref: quay.io/example/catalog-b:latest
+         ref: quay.io/example/content-management-b:latest
    ```
    NB: an `olm.operatorframework.io/metadata.name` label will be added automatically to ClusterCatalogs when applied
 
@@ -209,8 +209,8 @@ If the system cannot resolve to a single bundle due to ambiguity, it will genera
 3. **Apply the Resources**
 
    ```shell
-   kubectl apply -f catalog-a.yaml
-   kubectl apply -f catalog-b.yaml
+   kubectl apply -f content-management-a.yaml
+   kubectl apply -f content-management-b.yaml
    kubectl apply -f install-my-operator.yaml
    ```