eclipse-che · gtrivedi88 · Jul 7, 2026
@@ -1,6 +1,9 @@
 .Discover
 
 * xref:what-is-che.adoc[]
+* xref:what-problems-che-solves.adoc[]
+* xref:who-is-che-for.adoc[]
+* xref:when-to-use-che.adoc[]
 * xref:architecture-overview.adoc[]
 ** xref:server-components.adoc[]
 *** xref:che-operator.adoc[]

@@ -1,17 +1,15 @@
 :_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
+:navtitle: How the components fit together
+:page-aliases: administration-guide:architecture-overview.adoc, administration-guide:high-level-che-architecture.adoc, administration-guide:high-level-che-architecture-with-che-server.adoc, administration-guide:high-level-che-architecture-with-devworkspace.adoc, overview:architecture-overview.adoc, overview:high-level-che-architecture.adoc, overview:high-level-che-architecture-with-che-server.adoc, overview:high-level-che-architecture-with-devworkspace.adoc, overview:che-architecture.adoc
 
 [id="architecture"]
-= {prod-short} architecture
+= How the components fit together
 
 [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.
 
-include::partial$snip_persona-discover.adoc[]
-
 .High-level {prod-short} architecture with the {devworkspace} operator
 image::architecture/{project-context}-interacting-with-devworkspace.png[]
 
@@ -24,7 +22,7 @@ Manage User {orch-namespace} and workspaces. The main component is the User dash
 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.
+Container-based development environments, the Integrated Development Environment (IDE) included.
 
 The role of these {orch-name} features is central:
 

@@ -1,17 +1,15 @@
 :_content-type: CONCEPT
 :description: The devfile registry provides a list of sample devfiles for creating ready-to-use workspaces.
 :keywords: devfile, registry, samples, discover
-:navtitle: Devfile registry
+:navtitle: Devfile registry and workspace templates
 :page-aliases: administration-guide:che-devfile-registry.adoc
 
 [id="devfile-registry"]
-= Devfile registry
+= Devfile registry and workspace templates
 
 [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.
 
-include::partial$snip_persona-discover.adoc[]
-
 A devfile registry is a service providing a list of sample devfiles.
 You can use these samples to create ready-to-use workspaces.
 

@@ -1,20 +1,15 @@
 :_content-type: ASSEMBLY
 :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
+:navtitle: Operator and lifecycle management
 :page-aliases: administration-guide:che-operator.adoc
 
 [id="{prod-id-short}-operator"]
-= {prod-short} operator
+= Operator and lifecycle management
 
 [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.
 
-include::partial$snip_persona-discover.adoc[]
-
-The {prod-short} operator ensures full lifecycle management of the {prod-short} server components.
-It introduces:
-
 `CheCluster` custom resource definition (CRD)::
 Defines the `CheCluster` {orch-name} object.
 

@@ -1,17 +1,15 @@
 :_content-type: ASSEMBLY
 :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
+:navtitle: Server and namespace provisioning
 :page-aliases: administration-guide:che-server.adoc
 
 [id="{prod-id-short}-server-with-devworkspace"]
-= {prod-short} server
+= Server and namespace provisioning
 
 [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.
 
-include::partial$snip_persona-discover.adoc[]
-
 The {prod-short} server main functions are:
 
 * Creating user namespaces.

@@ -1,17 +1,15 @@
 :_content-type: ASSEMBLY
 :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
+:navtitle: Dashboard and workspace management
 :page-aliases: administration-guide:dashboard.adoc
 
 [id="dashboard"]
-= User dashboard
+= Dashboard and workspace management
 
 [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.
 
-include::partial$snip_persona-discover.adoc[]
-
 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. 

@@ -1,17 +1,15 @@
 :_content-type: ASSEMBLY
 :description: The {devworkspace} Operator (DWO) extends {orch-name} to manage workspace pods, services, and persistent volumes by reconciling {devworkspace} custom resources.
 :keywords: devworkspace, operator, architecture, discover
-:navtitle: {devworkspace} operator
+:navtitle: {devworkspace} Operator and workspace pods
 :page-aliases: administration-guide:devworkspace-operator.adoc, .:devworkspace-operator.adoc
 
 [id="devworkspace-operator"]
-= {devworkspace} Operator overview
+= {devworkspace} Operator and workspace pods
 
 [role="_abstract"]
 The {devworkspace} Operator (DWO) extends {orch-name} to manage workspace pods, services, and persistent volumes by reconciling {devworkspace} custom resources. Every {prod-short} workspace has an underlying {devworkspace} CR that contains the devfile, editor definition, and configuration attributes.
 
-include::partial$snip_persona-discover.adoc[]
-
 The {devworkspace} CR is a {orch-name} resource representation of a {prod-short} workspace. Whenever a user creates a workspace using {prod-short} in the background, Dashboard {prod-short} creates a {devworkspace} CR in the cluster. For every {prod-short} workspace, there is an underlying {devworkspace} CR on the cluster.
 
 .Example of a {devworkspace} CR in a cluster
@@ -127,7 +125,7 @@ where:
 
 `devworkspace-webhook-server-*`:: The {devworkspace} operator webhook server pods.
 
-== Configuring the {devworkspace}-controller-manager deployment
+== {devworkspace}-controller-manager deployment
 
 You can configure the `devworkspace-controller-manager` pod in the {devworkspace} Operator Subscription object:
 
@@ -152,7 +150,7 @@ spec:
         cpu: ...
 ----
 
-== Configuring the {devworkspace}-webhook-server deployment
+== {devworkspace}-webhook-server deployment
 
 You can configure the `devworkspace-webhook-server` deployment in the global DWOC:
 

@@ -1,17 +1,15 @@
 :_content-type: ASSEMBLY
 :description: The {prod-short} gateway routes requests, authenticates users with OpenID Connect (OIDC), and enforces {orch-name} RBAC policies.
 :keywords: gateway, architecture, traefik, authentication, discover
-:navtitle: Gateway
+:navtitle: Gateway and request routing
 :page-aliases: administration-guide:gateway.adoc
 
 [id="gateway"]
-= Gateway
+= Gateway and request routing
 
 [role="_abstract"]
 The {prod-short} gateway routes requests, authenticates users with OpenID Connect (OIDC), and enforces {orch-name} RBAC policies. It controls access to the dashboard, server, plug-in registry, and every user workspace.
 
-include::partial$snip_persona-discover.adoc[]
-
 The {prod-short} gateway has the following roles:
 
 * Routing requests. It uses link:https://github.com/traefik/traefik[Traefik].

@@ -1,22 +1,16 @@
 :_content-type: CONCEPT
 :description: The {prod-short} plug-in registry provides the list of available editors and editor extensions, each described by a Devfile v2.
 :keywords: plugin, registry, editors, extensions, discover
-:navtitle: Plugin registry
+:navtitle: Plug-in registry and editor definitions
 :page-aliases: administration-guide:plugin-registry.adoc, plug-in-registry
 
 [id="plugin-registry"]
-= Plugin registry
+= Plug-in registry and editor definitions
 
 [role="_abstract"]
 The {prod-short} plug-in registry provides the list of available editors and editor extensions, each described by a Devfile v2. The dashboard reads this registry when assembling the {devworkspace} custom resource for a new workspace.
 
-include::partial$snip_persona-discover.adoc[]
-
-Each {prod-short} workspace starts with a specific editor and set of associated extensions.
-The {prod-short} plugin registry provides the list of available editors and editor extensions.
-A Devfile v2 describes each editor or extension.
-
-The xref:dashboard.adoc[] is reading the content of the registry.
+The user dashboard reads the content of the registry.
 
 .Plugin registries interactions with other components
 image::architecture/{project-context}-plugin-registry-interactions.png[Plugin registries interactions with other components]

@@ -19,7 +19,8 @@ Common tasks include:
 * Deploy {prod-short} on a cluster. See xref:install:installing-che.adoc[].
 * Configure the `CheCluster` custom resource. See xref:administration-guide:understanding-the-checluster-custom-resource.adoc[].
 * Set up OAuth for Git providers. See xref:administration-guide:configuring-oauth-for-git-providers.adoc[].
-* Upgrade to the latest version. See xref:administration-guide:upgrading-che.adoc[].
+* Control workspace start times with image caching. See xref:optimize:caching-images-for-faster-workspace-start.adoc[].
+* Upgrade to the latest version. See xref:upgrade:upgrading-che.adoc[].
 * Monitor metrics and logs. See xref:administration-guide:configuring-observability.adoc[].
 
 == Developer
@@ -29,6 +30,7 @@ Developers create workspaces, write code, use IDE extensions, and integrate with
 
 Common tasks include:
 
-* Create a workspace from a Git repository. See xref:end-user-guide:starting-a-workspace-from-a-git-repository-url.adoc[].
-* Authenticate to Git servers. See xref:end-user-guide:using-a-git-provider-access-token.adoc[].
-* Configure IDE extensions. See xref:end-user-guide:microsoft-visual-studio-code-open-source-ide.adoc[].
+* Create a workspace from a Git repository. See xref:get-started:starting-a-workspace-from-a-git-repository-url.adoc[].
+* Authenticate to Git servers. See xref:get-started:using-a-git-provider-access-token.adoc[].
+* Install and manage IDE extensions. See xref:end-user-guide:microsoft-visual-studio-code-open-source-ide.adoc[].
+* Use devfiles to define workspace configuration. See xref:end-user-guide:devfile-introduction.adoc[].
@@ -1,16 +1,14 @@
 :_content-type: ASSEMBLY
-:description: The {prod-short} server components manage multi-tenancy and workspace lifecycle. Understanding these components helps you troubleshoot issues and plan cluster capacity.
+:description: The {prod-short} server components manage multi-tenancy and workspace lifecycle.
 :keywords: architecture, server, components, devworkspace, discover
-:navtitle: Server components
+:navtitle: What runs on your cluster
 :page-aliases: administration-guide:server-components.adoc
 
 [id="{prod-id-short}-server-components"]
-= {prod-short} server components
+= What runs on your cluster
 
 [role="_abstract"]
-The {prod-short} server components manage multi-tenancy and workspace lifecycle. Understanding these components helps you troubleshoot issues and plan cluster capacity.
-
-include::partial$snip_persona-discover.adoc[]
+The {prod-short} server components manage multi-tenancy and workspace lifecycle.
 
 .{prod-short} server components interacting with the {devworkspace} operator
 image::architecture/{project-context}-deployments-interacting-with-devworkspace.png[]

@@ -10,6 +10,4 @@
 [role="_abstract"]
 {prod-short} runs on a specific range of {orch-name} versions and CPU architectures. Confirm that your target cluster matches a supported combination before starting the installation.
 
-include::partial$snip_persona-discover.adoc[]
-
 include::example$snip_{project-context}-supported-platforms.adoc[]
@@ -1,17 +1,15 @@
 :_content-type: REFERENCE
 :description: User workspaces provide browser-based IDEs running in {orch-name} containers, giving developers on-demand access to editors, language servers, debugging tools, and application runtimes.
 :keywords: workspaces, architecture, devworkspace, discover
-:navtitle: User workspaces
+:navtitle: What developers get in a workspace
 :page-aliases: administration-guide:user-workspaces.adoc
 
 [id="user-workspaces"]
-= User workspaces
+= What developers get in a workspace
 
 [role="_abstract"]
 User workspaces provide browser-based IDEs running in {orch-name} containers, giving developers on-demand access to editors, language servers, debugging tools, and application runtimes without local setup.
 
-include::partial$snip_persona-discover.adoc[]
-
 .User workspaces interactions with other components
 image::architecture/{project-context}-user-workspaces-interactions.png[User workspaces interactions with other components]
 
@@ -45,4 +43,4 @@ The following diagram shows one running {prod-short} workspace and its component
 .{prod-short} workspace components
 image::workspace-components-with-dw.png[Workspace components]
 
-In the diagram, there is one running workspaces.
+In the diagram, there is one running workspace.
@@ -10,8 +10,6 @@
 [role="_abstract"]
 Evaluate {prod-short} as a cloud development platform that delivers container-based, reproducible workspaces on {platforms-name} to accelerate developer onboarding and reduce environment inconsistencies.
 
-include::partial$snip_persona-discover.adoc[]
-
 {prod} is a {kubernetes}-native platform that provides cloud development environments (CDEs) to development teams. Instead of configuring local machines, developers get on-demand workspaces: container-based environments with all the tools, dependencies, and IDE access needed to code, build, test, and debug applications.
 
 == Core goals

@@ -0,0 +1,34 @@
+:_content-type: CONCEPT
+:description: {prod-short} solves six common development workflow problems by providing ready-to-code cloud workspaces from Git repositories.
+:keywords: problems, onboarding, consistency, security, compliance
+:navtitle: What problems does {prod-short} solve?
+
+[id="what-problems-{prod-id-short}-solves"]
+= What problems does {prod-short} solve?
+
+[role="_abstract"]
+{prod-short} solves six common development workflow problems by providing ready-to-code cloud workspaces from Git repositories. Developers open a URL and start coding within minutes.
+
+== Environment inconsistency
+
+When every developer configures their own local environment, differences in operating system versions, tool versions, and dependencies cause "works on my machine" failures. {prod-short} uses devfiles, declarative YAML files that define the exact tools, runtimes, and dependencies for a project. Every developer who opens the same repository gets an identical environment.
+
+== Slow developer onboarding
+
+New team members must install tools, clone repositories, configure credentials, and troubleshoot build failures before writing their first line of code. With {prod-short}, a new developer opens the dashboard URL, pastes the team's repository link, and has a fully configured workspace within minutes.
+
+== Security and credential management
+
+Local development environments store credentials on individual laptops. {prod-short} centralizes credential management through OAuth integration with Git providers and {orch-name} RBAC. Developer tokens are stored as {orch-name} Secrets on the cluster, not on individual machines.
+
+== Environment drift over time
+
+Even teams that start with consistent environments drift as developers install different extensions, update tools independently, or modify configurations. {prod-short} rebuilds the workspace container from the devfile on each start, so the base toolchain is always consistent. The `/home/user` directory persists across restarts by default, preserving personal preferences and shell history without affecting the standardized tools and runtimes.
+
+== Resource constraints on developer laptops
+
+Complex projects with multiple microservices, databases, and build tools can overwhelm laptop hardware. {prod-short} runs workspaces on cluster infrastructure with configurable CPU, memory, and storage limits. Developers get the resources they need without upgrading their hardware.
+
+== Compliance in regulated environments
+
+Organizations in regulated industries need to control where code is developed and how it is accessed. {prod-short} runs entirely within your {orch-name} cluster and supports air-gapped environments with no internet access. In air-gapped deployments, all workspace traffic stays within your network boundary.