chore: promote Get Started to top-level Antora module (JTBD Phase 2)

antora.yml

@@ -7,6 +7,7 @@ start_page: discover:what-is-che.adoc
 nav:
   - modules/discover/nav.adoc
   - modules/install/nav.adoc
+  - modules/get-started/nav.adoc
   - modules/end-user-guide/nav.adoc
   - modules/upgrade/nav.adoc
   - modules/secure/nav.adoc

modules/end-user-guide/nav.adoc

@@ -1,32 +1,27 @@
 .User Guide
 
-* xref:getting-started-with-che.adoc[]
-** xref:starting-a-workspace-from-a-git-repository-url.adoc[]
-*** xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[]
-**** xref:url-parameter-concatenation.adoc[]
-**** xref:url-parameter-for-the-ide.adoc[]
-**** xref:url-parameter-for-the-ide-image.adoc[]
-**** xref:url-parameter-for-starting-duplicate-workspaces.adoc[]
-**** xref:url-parameter-for-the-devfile-file-name.adoc[]
-**** xref:url-parameter-for-the-devfile-file-path.adoc[]
-**** xref:url-parameter-for-the-workspace-storage.adoc[]
-**** xref:url-parameter-for-additional-remotes.adoc[]
-**** xref:url-parameter-for-container-image.adoc[]
-**** xref:url-parameter-for-memory-limit.adoc[]
-**** xref:url-parameter-for-cpu-limit.adoc[]
-**** xref:url-parameter-for-the-existing-workspace-name.adoc[]
-**** xref:url-parameter-for-the-ai-provider.adoc[]
-** xref:starting-a-workspace-from-a-raw-devfile-url.adoc[]
-** xref:basic-actions-you-can-perform-on-a-workspace.adoc[]
-** xref:restoring-workspaces-from-backups.adoc[]
-*** xref:proc-restoring-a-workspace-from-backup.adoc[]
-*** xref:proc-viewing-backups-in-the-dashboard.adoc[]
-** xref:authenticating-to-a-git-server-from-a-workspace.adoc[]
-** xref:using-the-fuse-overlay-storage-driver.adoc[]
-*** xref:accessing-fuse.adoc[]
-*** xref:enabling-overlay-with-a-configmap.adoc[]
-** xref:running-containers-with-kubedock.adoc[]
-** xref:proc_preventing-workspace-idling-for-long-running-commands.adoc[]
+* xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[]
+** xref:url-parameter-concatenation.adoc[]
+** xref:url-parameter-for-the-ide.adoc[]
+** xref:url-parameter-for-the-ide-image.adoc[]
+** xref:url-parameter-for-starting-duplicate-workspaces.adoc[]
+** xref:url-parameter-for-the-devfile-file-name.adoc[]
+** xref:url-parameter-for-the-devfile-file-path.adoc[]
+** xref:url-parameter-for-the-workspace-storage.adoc[]
+** xref:url-parameter-for-additional-remotes.adoc[]
+** xref:url-parameter-for-container-image.adoc[]
+** xref:url-parameter-for-memory-limit.adoc[]
+** xref:url-parameter-for-cpu-limit.adoc[]
+** xref:url-parameter-for-the-existing-workspace-name.adoc[]
+** xref:url-parameter-for-the-ai-provider.adoc[]
+* xref:restoring-workspaces-from-backups.adoc[]
+** xref:proc-restoring-a-workspace-from-backup.adoc[]
+** xref:proc-viewing-backups-in-the-dashboard.adoc[]
+* xref:using-the-fuse-overlay-storage-driver.adoc[]
+** xref:accessing-fuse.adoc[]
+** xref:enabling-overlay-with-a-configmap.adoc[]
+* xref:running-containers-with-kubedock.adoc[]
+* xref:proc_preventing-workspace-idling-for-long-running-commands.adoc[]
 * xref:using-che-in-team-workflow.adoc[]
 ** xref:first-time-contributors.adoc[]
 ** xref:benefits-of-pull-requests-review-in-che.adoc[]
@@ -43,7 +38,7 @@
 * xref:using-credentials-and-configurations-in-workspaces.adoc[]
 ** xref:mounting-secrets.adoc[]
 *** xref:creating-image-pull-secrets.adoc[]
-*** xref:using-a-git-provider-access-token.adoc[]
+*** xref:get-started:using-a-git-provider-access-token.adoc[]
 ** xref:mounting-configmaps.adoc[]
 *** xref:mounting-git-configuration.adoc[]
 *** xref:mounting-ssh-configuration.adoc[]

modules/get-started/nav.adoc

@@ -0,0 +1,7 @@
+.Get Started
+* xref:your-first-workspace.adoc[]
+* xref:starting-a-workspace-from-a-git-repository-url.adoc[]
+* xref:basic-actions-you-can-perform-on-a-workspace.adoc[]
+* xref:authenticating-to-a-git-server-from-a-workspace.adoc[]
+** xref:using-a-git-provider-access-token.adoc[]
+* xref:starting-a-workspace-from-a-raw-devfile-url.adoc[]

modules/end-user-guide/pages/authenticating-to-a-git-server-from-a-workspace.adoc → modules/get-started/pages/authenticating-to-a-git-server-from-a-workspace.adoc

@@ -1,14 +1,16 @@
 :_content-type: CONCEPT
 :description: Authenticating to a Git server from a workspace
 :keywords: authentication, authenticate, github, gitlab, bitbucket
-:navtitle: Authenticating to a Git server from a workspace
-:page-aliases:
+:navtitle: How Git authentication works in Cloud Development Environments
+:page-aliases: end-user-guide:authenticating-to-a-git-server-from-a-workspace.adoc
 
 [id="authenticating-to-a-git-server-from-a-workspace"]
-= Authenticating to a Git server from a workspace
+= How Git authentication works in Cloud Development Environments
 
 pass:[<!-- vale RedHat.CaseSensitiveTerms = NO -->]
 
+include::partial$snip_persona-developer.adoc[]
+
 In a workspace, you can run Git commands that require user authentication like cloning a remote private Git repository or pushing to a remote public or private Git repository.
 
 User authentication to a Git server from a workspace is configured by the administrator or, in some cases, by the individual user:

modules/end-user-guide/pages/basic-actions-you-can-perform-on-a-workspace.adoc → modules/get-started/pages/basic-actions-you-can-perform-on-a-workspace.adoc

@@ -1,14 +1,16 @@
 :_content-type: REFERENCE
 :description: Basic actions you can perform on a workspace
 :keywords: workspace, workspaces, reopen, restart, stop, start, delete
-:navtitle: Basic actions you can perform on a workspace
-:page-aliases:
+:navtitle: Manage your Cloud Development Environments
+:page-aliases: end-user-guide:basic-actions-you-can-perform-on-a-workspace.adoc
 
 [id="basic-actions-you-can-perform-on-a-workspace"]
-= Basic actions you can perform on a workspace
+= Manage your Cloud Development Environments
 
 You manage your workspaces and verify their current states in the *Workspaces* page (`pass:c,a,q[{prod-url}]/dashboard/#/workspaces`) of your {prod-short} dashboard.
 
+include::partial$snip_persona-developer.adoc[]
+
 After you start a new workspace, you can perform the following actions on it in the *Workspaces* page:
 
 .Basic actions you can perform on a workspace
@@ -31,3 +33,5 @@ After you start a new workspace, you can perform the following actions on it in
 | Go to *⋮* *>* *Delete Workspace*.
 
 |===
+
+NOTE: Each workspace is a {orch-name} `DevWorkspace` custom resource. You can also manage workspaces from the command line with `{orch-cli}` or `kubectl`. See xref:end-user-guide:managing-workspaces-with-apis.adoc[].

modules/end-user-guide/pages/starting-a-workspace-from-a-git-repository-url.adoc → modules/get-started/pages/starting-a-workspace-from-a-git-repository-url.adoc

@@ -1,11 +1,11 @@
 :_content-type: PROCEDURE
 :description: Starting a workspace from a Git repository URL
 :keywords: start-new-workspace, start-a-new-workspace, how-to-start-new-workspace, how-to-start-a-new-workspace, starting-a-new-workspace, clone-git-repository, clone-a-git-repository, how-to-start-workspace, how-to-start-a-workspace
-:navtitle: Starting a workspace from a Git repository URL
-:page-aliases:
+:navtitle: Open your project in a Cloud Development Environment
+:page-aliases: end-user-guide:starting-a-workspace-from-a-git-repository-url.adoc
 
 [id="starting-a-workspace-from-a-git-repository-url"]
-= Starting a workspace from a Git repository URL
+= Open your project in a Cloud Development Environment
 
 In the context of this procedure, "Git repository URL" refers to a git clone URL of a repository. Usually, you can fetch this URL by clicking on the *Clone* button in the SCM repository's main page.
 Alternatively, you can copy the URL from the address bar of your browser when you are on the main page of the repository.
@@ -15,6 +15,8 @@ Selecting a branch or a tag will add the reference parameter to the URL.
 For GitHub, you can also use a repository URL of a directory with a devfile, or a repository URL of the devfile.
 The name of the devfile must be `devfile.yaml` or `.devfile.yaml`.
 
+include::partial$snip_persona-developer.adoc[]
+
 This feature is not supported for other Git providers.
 ====
 
@@ -40,7 +42,7 @@ Configure personal access token to access private repositories. See xref:using-a
 * Your organization has a running instance of {prod-short}.
 * You know the FQDN URL of your organization's {prod-short} instance: `pass:c,a,q[{prod-url}]`.
 * Optional: You have xref:authenticating-to-a-git-server-from-a-workspace.adoc[authentication to the Git server] configured.
-* Your Git repository maintainer keeps the `devfile.yaml` or `.devfile.yaml` file in the root directory of the Git repository. (For alternative file names and file paths, see xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[].)
+* Your Git repository maintainer keeps the `devfile.yaml` or `.devfile.yaml` file in the root directory of the Git repository. (For alternative file names and file paths, see xref:end-user-guide:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[].)
 +
 TIP: You can also start a new workspace by supplying the URL of a Git repository that contains no devfile. Doing so results in a workspace with Universal Developer Image and with Microsoft Visual Studio Code - Open Source as the workspace IDE.
 //provide a link to a page about the Universal Developer Image similar to https://developers.redhat.com/products/rhel/ubi for UBI and, if applicable, devfile-less defaults for new workspaces. max-cx
@@ -65,7 +67,7 @@ You can extend this URL with optional parameters:
 ----
 pass:c,a,q[{prod-url}]#__<git_repository_url>__?__<optional_parameters>__ <1>
 ----
-<1> See xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[].
+<1> See xref:end-user-guide:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[].
 ====
 +
 [TIP]
@@ -128,8 +130,8 @@ The workspace has a unique URL: `pass:c,a,q[{prod-url}]/__<user_name>__/__<uniqu
 
 .Additional resources
 
-* xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[]
+* xref:end-user-guide:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[]
 * xref:basic-actions-you-can-perform-on-a-workspace.adoc[]
 * xref:using-a-git-provider-access-token.adoc[]
-* xref:mounting-git-configuration.adoc[]
+* xref:end-user-guide:mounting-git-configuration.adoc[]
 * link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#configuring-devworkspaces-to-use-ssh-keys-for-git-operations[Configuring DevWorkspaces to use SSH keys for Git operations]

modules/end-user-guide/pages/starting-a-workspace-from-a-raw-devfile-url.adoc → modules/get-started/pages/starting-a-workspace-from-a-raw-devfile-url.adoc

@@ -1,14 +1,16 @@
 :_content-type: PROCEDURE
 :description: Starting a workspace from a raw devfile URL
 :keywords: start-new-workspace, start-a-new-workspace, how-to-start-new-workspace, how-to-start-a-new-workspace, starting-a-new-workspace, how-to-start-workspace, how-to-start-a-workspace
-:navtitle: Starting a workspace from a raw devfile URL
-:page-aliases:
+:navtitle: Start a Cloud Development Environment from a raw devfile URL
+:page-aliases: end-user-guide:starting-a-workspace-from-a-raw-devfile-url.adoc
 
 [id="starting-a-workspace-from-a-raw-devfile-url"]
-= Starting a workspace from a raw devfile URL
+= Start a Cloud Development Environment from a raw devfile URL
 
 With {prod-short}, you can open a *devfile* URL in your browser to start a new workspace.
 
+include::partial$snip_persona-developer.adoc[]
+
 pass:[<!-- vale RedHat.Spelling = NO -->]
 
 TIP: You can use the *Git Repo URL* field on the *Create Workspace* page of your {prod-short} dashboard to enter the URL of a *devfile* to start a new workspace.
@@ -64,7 +66,7 @@ You can extend this URL with optional parameters:
 ----
 pass:c,a,q[{prod-url}]#__<devfile_url>__?__<optional_parameters>__ <1>
 ----
-<1> See xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[].
+<1> See xref:end-user-guide:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[].
 ====
 +
 .A URL for starting a new workspace from a public repository
@@ -89,8 +91,8 @@ The workspace has a unique URL: `pass:c,a,q[{prod-url}]/__<user_name>__/__<uniqu
 
 .Additional resources
 
-* xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[]
+* xref:end-user-guide:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[]
 * xref:basic-actions-you-can-perform-on-a-workspace.adoc[]
 * xref:using-a-git-provider-access-token.adoc[]
-* xref:mounting-git-configuration.adoc[]
+* xref:end-user-guide:mounting-git-configuration.adoc[]
 * link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#configuring-devworkspaces-to-use-ssh-keys-for-git-operations[Configuring DevWorkspaces to use SSH keys for Git operations]

modules/end-user-guide/pages/using-a-git-provider-access-token.adoc → modules/get-started/pages/using-a-git-provider-access-token.adoc

@@ -1,14 +1,16 @@
 :_content-type: PROCEDURE
 :description: Using a Git-provider access token
 :keywords: Git, credentials, access-token
-:navtitle: Using a Git-provider access token
-:page-aliases: using-a-Git-credentials-store.adoc, using-git-credentials.adoc, 
+:navtitle: Access private repositories with a personal access token
+:page-aliases: end-user-guide:using-a-git-provider-access-token.adoc, using-a-Git-credentials-store.adoc, using-git-credentials.adoc, 
 
 [id="using-a-git-provider-access-token"]
-= Using a Git-provider access token
+= Access private repositories with a personal access token
 
 pass:[<!-- vale RedHat.CaseSensitiveTerms = NO -->]
 
+include::partial$snip_persona-developer.adoc[]
+
 OAuth for GitHub, GitLab, Bitbucket, or Microsoft Azure Repos needs to be xref:administration-guide:configuring-oauth-for-git-providers.adoc[configured by the administrator] of your organization's {prod-short} instance. If your administrator could not configure it for {prod-short} users, the workaround is for you to use a personal access token. You can configure personal access tokens on the *User Preferences* page of your {prod-short} dashboard: `pass:c,a,q[{prod-url}]/dashboard/#/user-preferences?tab=personal-access-tokens`, or apply it manually as a {kubernetes} Secret in the namespace.
 
 Mounting your access token as a Secret enables the {prod-short} Server to access the remote repository that is cloned during workspace creation, including access to the repository's `/.che` and `/.vscode` folders.
@@ -119,7 +121,7 @@ EOF
 
 [IMPORTANT]
 ====
-If you are using Azure DevOps Server, you must also modify the xref:mounting-git-configuration.adoc[workspace's
+If you are using Azure DevOps Server, you must also modify the xref:end-user-guide:mounting-git-configuration.adoc[workspace's
 gitconfig] with the following section:
 
 [source,http]

modules/get-started/pages/your-first-workspace.adoc

@@ -0,0 +1,77 @@
+:_content-type: CONCEPT
+:description: Go from opening the {prod-short} URL to coding in about three minutes.
+:keywords: getting started, first workspace, onboarding
+:navtitle: Your first-day experience
+
+[id="your-first-workspace"]
+= Your first-day experience
+
+[role="_abstract"]
+{prod-short} creates a Cloud Development Environment (CDE) for your project. The dashboard and CLI refer to each CDE as a *workspace*. Each Cloud Development Environment runs as a {orch-name} `DevWorkspace` custom resource on your cluster. You go from login to coding in about three minutes.
+
+include::partial$snip_persona-developer.adoc[]
+
+== From URL to code in four steps
+
+When your administrator shares the {prod-short} dashboard URL, you go from login to coding in four steps:
+
+. *Authenticate* -- {prod-short} redirects you to the login page. Enter your credentials and authorize {prod-short} to access your account.
+
+. *Create Workspace page* -- After authentication, you land on the Create Workspace page. The page has two main sections:
++
+** *Git Repo URL* -- A field where you paste the HTTPS or SSH URL of your Git repository.
+** *Select a Sample* -- Pre-configured workspace samples for languages and frameworks such as Java, Node.js, Python, and Go. Use these to explore {prod-short} without connecting your own repository.
+
+. *Start your workspace* -- When you enter a Git URL and click *Create & Open*, {prod-short} asks you to confirm that you trust the repository authors, then provisions the workspace.
+
+. *IDE loads in your browser* -- The default IDE, Microsoft Visual Studio Code - Open Source, opens in your browser tab with the repository already cloned.
+
+== Why does the first start take longer?
+
+The first workspace start takes approximately 2-3 minutes because {prod-short} pulls container images to the cluster node. The workspace starting page displays real-time progress, including:
+
+* Volume provisioning for persistent storage
+* Container image pulls for the development tools and IDE
+* Initialization of the project clone, home directory, and IDE server
+
+Subsequent starts are faster because {platforms-name} caches the container images on the node. If your administrator has deployed the {image-puller-name-short}, images are pre-cached across all nodes for near-instant starts.
+
+== What can you do in a Cloud Development Environment?
+
+A running {prod-short} workspace provides:
+
+Terminal:: A `bash` terminal in the IDE with your project directory as the working directory. The terminal prompt shows the current Git branch.
+
+Git integration:: Your repository is cloned into the workspace filesystem. If your administrator has configured OAuth for your Git provider, you can push commits without re-entering credentials.
+
+Development tools:: The Universal Developer Image (UDI) includes compilers, runtimes, and build tools for common languages. Your project's `devfile.yaml` can define additional tools and commands.
+
+Workspace URL:: Each workspace has a unique URL in the format `pass:c,a,q[{prod-url}]/__<user_name>__/__<workspace_name>__/`. Bookmark this URL to return to a running workspace.
+
+== Something went wrong?
+
+Workspace fails to start with `OOMKilled` or `FailedScheduling`::
+Your {orch-namespace} exceeded its resource quota, or the workspace requested more memory or CPU than the cluster allows. Contact your administrator to adjust resource limits.
+
+Git push returns `401 Unauthorized` or `403 Forbidden`::
+OAuth is not configured for your Git provider, or your token has expired. Configure authentication to resolve this issue.
+
+Blank IDE with a `Could not register service workers` error::
+This error occurs in Google Chrome Incognito mode or Mozilla Firefox Private Browsing mode. Use a regular browser window instead.
+
+.Additional resources
+
+* xref:authenticating-to-a-git-server-from-a-workspace.adoc[]
+
+== Joining the community
+
+Public chat::
+Join the public link:https://communityinviter.com/apps/ecd-tools/join-the-community[Eclipse Cloud Dev Tools Working Group on Slack]
+and the link:https://ecd-tools.slack.com/archives/C05SD64M85R[#forum-che channel]
+to chat with the developers.
+
+GitHub project repositories::
+Report bugs, request features, and contribute in the main link:https://github.com/eclipse/che[{prod} repository].
+
+Community meetings::
+Join us in the link:https://github.com/eclipse/che/wiki/{prod-id}-community-meetings[{prod-short} community meeting], available on-demand.

modules/get-started/partials/snip_persona-developer.adoc

@@ -0,0 +1 @@
+This page is for developers who create and use cloud development environments. To learn more about common roles and example tasks referenced in {prod-short} documentation, see xref:discover:roles-and-tasks.adoc[].

modules/hosted-che/partials/assembly_hosted-che.adoc

@@ -21,5 +21,5 @@ include::partial$ref_hosted-che-faq-and-troubleshooting.adoc[leveloffset=+1]
 
 .Additional resources
 
-* For general end-user guidance, see xref:end-user-guide:getting-started-with-che.adoc[].
+* For general end-user guidance, see xref:get-started:your-first-workspace.adoc[].
 

modules/install/pages/con_next-steps-after-installation.adoc

@@ -17,4 +17,4 @@ After a successful installation, a few configuration tasks remain before your te
 
 * xref:administration-guide:understanding-the-checluster-custom-resource.adoc[]
 * xref:administration-guide:configuring-oauth-for-git-providers.adoc[]
-* xref:end-user-guide:starting-a-workspace-from-a-git-repository-url.adoc[]
+* xref:get-started:starting-a-workspace-from-a-git-repository-url.adoc[]