chore: create Discover category with JTBD restructure

antora.yml

@@ -7,6 +7,7 @@ start_page: overview:introduction-to-eclipse-che.adoc
 nav:
   - modules/overview/nav.adoc
   - modules/hosted-che/nav.adoc
+  - modules/discover/nav.adoc
   - modules/end-user-guide/nav.adoc
   - modules/administration-guide/nav.adoc
   - modules/extensions/nav.adoc
@@ -133,6 +134,6 @@ ext:
   - run:
       command: ./tools/create_architecture_diagrams.py
     scan:
-      base: modules/administration-guide/images/architecture/
+      base: modules/discover/images/architecture/
       dir: build/collector/architecture-diagrams
       files: '*.png'

modules/administration-guide/nav.adoc

@@ -2,18 +2,7 @@
 
 * xref:security-best-practices.adoc[]
 * xref:preparing-the-installation.adoc[]
-** xref:supported-platforms.adoc[]
 ** xref:installing-the-chectl-management-tool.adoc[]
-** xref:architecture-overview.adoc[]
-*** xref:server-components.adoc[]
-**** xref:che-operator.adoc[]
-**** xref:devworkspace-operator.adoc[]
-**** xref:gateway.adoc[]
-**** xref:dashboard.adoc[]
-**** xref:che-server.adoc[]
-**** xref:che-devfile-registry.adoc[]
-**** xref:plugin-registry.adoc[]
-*** xref:user-workspaces.adoc[]
 ** xref:calculating-che-resource-requirements.adoc[]
 * xref:running-at-scale.adoc[]
 // Install

modules/administration-guide/pages/configuring-storage-classes.adoc

@@ -22,7 +22,7 @@ Persistent volume claims facts:
 
 * {prod-short} does not create persistent volumes in the infrastructure.
 * {prod-short} uses persistent volume claims (PVC) to mount persistent volumes.
-* The xref:devworkspace-operator.adoc[Dev Workspace operator] creates persistent volume claims.
+* The xref:discover:devworkspace-operator.adoc[Dev Workspace operator] creates persistent volume claims.
 +
 Define a storage class name in the {prod-short} configuration to use the storage classes feature in the {prod-short} PVC.
 

modules/administration-guide/pages/devworkspace-backup-integrated-openshift-registry.adoc

@@ -31,7 +31,7 @@ config:
       schedule: '0 */4 * * *' # cron expression with backup frequency
     imagePullPolicy: Always
 ----
-<1> For Red Hat OpenShift, the default installation namespace for the {devworkspace} operator is `openshift-operators`. See the xref:devworkspace-operator.adoc[{devworkspace} operator overview].
+<1> For Red Hat OpenShift, the default installation namespace for the {devworkspace} operator is `openshift-operators`. See the xref:discover:devworkspace-operator.adoc[{devworkspace} operator overview].
 <2> The `--insecure` flag can be required depending on the integrated registry's routing configuration.
 
 **Note:** The `path` field must contain the URL to your OpenShift integrated registry given by the cluster.

modules/administration-guide/pages/devworkspace-backup-regular-oci-registry.adoc

@@ -31,7 +31,7 @@ config:
       schedule: '0 */4 * * *'
     imagePullPolicy: Always
 ----
-<1> For Red Hat OpenShift, the default installation namespace for the {devworkspace} operator is `openshift-operators`. See the xref:devworkspace-operator.adoc[{devworkspace} operator overview].
+<1> For Red Hat OpenShift, the default installation namespace for the {devworkspace} operator is `openshift-operators`. See the xref:discover:devworkspace-operator.adoc[{devworkspace} operator overview].
 
 The `authSecret` must be named `devworkspace-backup-registry-auth`. It must reference a {kubernetes} Secret of type `kubernetes.io/dockerconfigjson` that contains credentials to access the registry.
 The secret should be created in the installation {namespace} for the {devworkspace} operator.

modules/administration-guide/pages/preparing-the-installation.adoc

@@ -7,10 +7,10 @@
 [id="preparing-the-installation"]
 = Preparing the installation
 
-To prepare a {prod-short} installation, learn about the {prod-short} ecosystem and deployment constraints:
+To prepare a {prod-short} installation, review the platform requirements and deployment tools:
 
-* xref:supported-platforms.adoc[]
+* xref:discover:supported-platforms.adoc[]
+* xref:discover:architecture-overview.adoc[]
 * xref:installing-the-chectl-management-tool.adoc[]
-* xref:architecture-overview.adoc[]
 * xref:calculating-che-resource-requirements.adoc[]
 * xref:understanding-the-checluster-custom-resource.adoc[]

modules/administration-guide/partials/snip_defining-dwo-namespace-for-backups.adoc

@@ -18,5 +18,5 @@ spec:
                 value: $OPERATOR_INSTALL_NAMESPACE <1>
             name: che-dashboard
 ----
-<1> For Red Hat OpenShift, the default installation namespace for the {devworkspace} operator is `openshift-operators`. See the xref:devworkspace-operator.adoc[{devworkspace} operator overview].
+<1> For Red Hat OpenShift, the default installation namespace for the {devworkspace} operator is `openshift-operators`. See the xref:discover:devworkspace-operator.adoc[{devworkspace} operator overview].
 ====

modules/administration-guide/examples/snip_che-supported-platforms.adoc → modules/discover/examples/snip_che-supported-platforms.adoc

@@ -23,4 +23,4 @@ The following options are available for the local installation:
 
 .Additional resources
 
-* xref:installing-che.adoc[]
+* xref:administration-guide:installing-che.adoc[]

modules/discover/nav.adoc

@@ -0,0 +1,13 @@
+.Discover
+
+* xref:architecture-overview.adoc[]
+** xref:server-components.adoc[]
+*** xref:che-operator.adoc[]
+*** xref:devworkspace-operator.adoc[]
+*** xref:gateway.adoc[]
+*** xref:dashboard.adoc[]
+*** xref:che-server.adoc[]
+*** xref:che-devfile-registry.adoc[]
+*** xref:plugin-registry.adoc[]
+** xref:user-workspaces.adoc[]
+* xref:supported-platforms.adoc[]

modules/discover/pages/architecture-overview.adoc

@@ -0,0 +1,42 @@
+:_content-type: CONCEPT
+:description: {prod-short} runs on three groups of components — server components, the {devworkspace} Operator, and user workspaces — that communicate through {devworkspace} custom resources on {orch-name}.
+:keywords: architecture, discover, components, devworkspace
+:navtitle: Architecture overview
+:page-aliases: administration-guide:architecture-overview.adoc, .:che-architecture-overview.adoc, .:high-level-che-architecture.adoc, overview:high-level-che-architecture.adoc, administration-guide:high-level-che-architecture.adoc, che-architecture-overview.adoc, .:che-architecture-overview-with-che-server.adoc, .:high-level-che-architecture-with-che-server.adoc, overview:high-level-che-architecture-with-che-server.adoc, administration-guide:high-level-che-architecture-with-che-server.adoc, .:che-architecture-overview-with-devworkspace.adoc, .:high-level-che-architecture-with-devworkspace.adoc, overview:high-level-che-architecture-with-devworkspace.adoc, administration-guide:high-level-che-architecture-with-devworkspace.adoc, architecture-overview-with-devworkspace.adoc, architecture-overview-with-che-server, server-components-with-che-server.adoc, che-workspaces-architecture-with-che-server.adoc, backup-and-recovery.adoc, supported-restic-compatible-backup-servers.adoc, backing-up-of-che-instances-to-an-sftp-backup-server.adoc, backing-up-of-che-instances-to-amazon-s3.adoc, backing-up-of-che-instances-to-a-rest-backup-server.adoc, backing-up-of-che-instances-to-the-internal-backup-server.adoc, restoring-a-che-instance-from-a-backup.adoc, backups-of-persistent-volumes.adoc, readiness-init-containers.adoc, enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc, enabling-readiness-init-containers-for-the-operator-installer.adoc, disabling-readiness-init-containers-for-the-operator-installer.adoc, enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc, enabling-readiness-init-containers-for-the-olm-installer.adoc, disabling-readiness-init-containers-for-the-olm-installer.adoc, overview:architecture-overview.adoc, overview:che-architecture.adoc
+
+[id="architecture"]
+= {prod-short} architecture
+
+[role="_abstract"]
+{prod-short} runs on three groups of components — server components, the {devworkspace} Operator, and user workspaces — that communicate through {devworkspace} custom resources on {orch-name}. Each group has a distinct role in delivering cloud development environments, and {orch-name} RBAC controls access to all resources.
+
+.High-level {prod-short} architecture with the {devworkspace} operator
+image::architecture/{project-context}-interacting-with-devworkspace.png[]
+
+{prod-short} runs on three groups of components:
+
+{prod-short} server components::
+Manage User {orch-namespace} and workspaces. The main component is the User dashboard, from which users control their workspaces.
+
+{devworkspace} operator::
+Creates and controls the necessary {orch-name} objects to run User workspaces. Including `Pods`, `Services`, and `PersistentVolumes`.
+
+User workspaces:: 
+Container-based development environments, the IDE included.
+
+The role of these {orch-name} features is central:
+
+{devworkspace} Custom Resources::
+Valid {orch-name} objects representing the User workspaces and manipulated by {prod-short}. It is the communication channel for the three groups of components.
+
+{orch-name} role-based access control (RBAC):: 
+Controls access to all resources.
+
+.Additional resources
+
+* xref:server-components.adoc[]
+* xref:devworkspace-operator.adoc[]
+* xref:user-workspaces.adoc[]
+* link:https://github.com/devfile/devworkspace-operator[{devworkspace} Operator repository]
+
+include::example$snip_che-architecture-overview-with-devworkspace-additional-resources.adoc[]

modules/administration-guide/pages/che-devfile-registry.adoc → modules/discover/pages/che-devfile-registry.adoc

@@ -1,12 +1,15 @@
 :_content-type: CONCEPT
-:description: Devfile registry
-:keywords: administration-guide, devfile
+:description: The devfile registry provides a list of sample devfiles for creating ready-to-use workspaces.
+:keywords: devfile, registry, samples, discover
 :navtitle: Devfile registry
-:page-aliases:
+:page-aliases: administration-guide:che-devfile-registry.adoc
 
 [id="devfile-registry"]
 = Devfile registry
 
+[role="_abstract"]
+The devfile registry provides a list of sample devfiles for creating ready-to-use workspaces. Use these samples as starting points for your development environments.
+
 A devfile registry is a service providing a list of sample devfiles.
 You can use these samples to create ready-to-use workspaces.
 

modules/administration-guide/pages/che-operator.adoc → modules/discover/pages/che-operator.adoc

@@ -1,13 +1,16 @@
 :_content-type: ASSEMBLY
-:description: Components of {prod-short} operator
-:keywords: administration-guide, architecture, operator
+:description: The {prod-short} Operator manages the full lifecycle of {prod-short} server components through the CheCluster custom resource.
+:keywords: operator, architecture, lifecycle, discover
 :navtitle: {prod-short} operator
-:page-aliases:
+:page-aliases: administration-guide:che-operator.adoc
 
 [id="{prod-id-short}-operator"]
 = {prod-short} operator
 
-The {prod-short} operator ensure full lifecycle management of the {prod-short} server components. 
+[role="_abstract"]
+The {prod-short} Operator manages the full lifecycle of {prod-short} server components through the `CheCluster` custom resource. Creating a `CheCluster` CR triggers the Operator to deploy the {devworkspace} Operator, gateway, dashboard, server, and plug-in registry.
+
+The {prod-short} operator ensures full lifecycle management of the {prod-short} server components.
 It introduces:
 
 `CheCluster` custom resource definition (CRD)::
@@ -28,5 +31,5 @@ On a cluster with the {prod-short} operator, it is possible to create a `CheClus
 
 .Additional resources
 
-* xref:understanding-the-checluster-custom-resource.adoc[]
-* xref:installing-che.adoc[]
+* xref:administration-guide:understanding-the-checluster-custom-resource.adoc[]
+* xref:administration-guide:installing-che.adoc[]

modules/administration-guide/pages/che-server.adoc → modules/discover/pages/che-server.adoc

@@ -1,12 +1,14 @@
 :_content-type: ASSEMBLY
-:description: Functions of {prod-short} server
-:keywords: administration-guide, architecture, server, devworkspace
+:description: The {prod-short} server is a Java web service that creates user namespaces, provisions them with secrets and config maps, and integrates with Git service providers.
+:keywords: server, architecture, namespaces, git, discover
 :navtitle: {prod-short} server
-:page-aliases:
+:page-aliases: administration-guide:che-server.adoc
 
 [id="{prod-id-short}-server-with-devworkspace"]
 = {prod-short} server
 
+[role="_abstract"]
+The {prod-short} server is a Java web service that creates user namespaces, provisions them with secrets and config maps, and integrates with Git service providers for devfile fetching and authentication.
 
 The {prod-short} server main functions are:
 
@@ -24,6 +26,6 @@ image::architecture/{project-context}-server-interactions.png[{prod-short} serve
 
 .Additional resources
 
-* xref:advanced-configuration-options-for-the-che-server-component.adoc[]
+* xref:administration-guide:advanced-configuration-options-for-the-che-server-component.adoc[]
 
 include::example$snip_{project-context}-che-server-additional-resources.adoc[]

modules/administration-guide/pages/dashboard.adoc → modules/discover/pages/dashboard.adoc

@@ -1,12 +1,15 @@
 :_content-type: ASSEMBLY
-:description: User dashboard
-:keywords: administration-guide, architecture, server, devworkspace, user, dashboard
+:description: The user dashboard is the landing page of {prod} where users create, manage, and access their workspaces.
+:keywords: dashboard, architecture, user interface, discover
 :navtitle: User dashboard
-:page-aliases:
+:page-aliases: administration-guide:dashboard.adoc
 
 [id="dashboard"]
 = User dashboard
 
+[role="_abstract"]
+The user dashboard is the landing page of {prod} where users create, manage, and access their workspaces. It coordinates with the {prod-short} server, plug-in registry, and {orch-name} API to convert devfiles into running workspace pods.
+
 The user dashboard is the landing page of {prod}.
 {prod-short} users browse the user dashboard to access and manage their workspaces.
 It is a React application.