procedures: starting a new workspace

antora-playbook-for-development.yml

@@ -16,7 +16,7 @@ site:
   title: Eclipse Che Documentation
   # Disabling url on purpose to avoid htmltest crawling the live website.
   # url: https://www.eclipse.org/che/docs
-  start_page: docs:user-guide:starting-a-workspace-using-the-dashboard.adoc
+  start_page: docs:user-guide:user-onboarding.adoc
   robots: allow
 content:
   sources:

antora.yml

@@ -12,7 +12,7 @@ title: Documentation
 prerelease: true
 version: main
 display_version: main
-start_page: user-guide:starting-a-workspace-using-the-dashboard.adoc
+start_page: user-guide:user-onboarding.adoc
 nav:
   - modules/overview/nav.adoc
   - modules/hosted-che/nav.adoc
@@ -90,7 +90,7 @@ asciidoc:
     prod-operator: che-operator
     prod-short: Che
     prod-upstream: Eclipse{nbsp}Che
-    prod-url: https://che-host:che-port
+    prod-url: https://<i><</i><i>che_fqdn</i><i>></i>
     prod-workspace: che-ws
     prod: Eclipse&#160;Che
     prod2: Eclipse&#160;Che

modules/installation-guide/examples/system-variables.adoc

@@ -245,7 +245,9 @@ pass:[<!-- vale off -->]
  `+CHE_INFRA_KUBERNETES_ASYNC_STORAGE_SHUTDOWN__CHECK__PERIOD__MIN+`,"`+30+`","Defines the period with which the Asynchronous Storage Pod stopping ability will be performed (once in 30 minutes by default)" 
  `+CHE_INTEGRATION_BITBUCKET_SERVER__ENDPOINTS+`,"`+NULL+`","Bitbucket endpoints used for factory integrations. Comma separated list of Bitbucket server URLs or NULL if no integration expected." 
  `+CHE_INTEGRATION_GITLAB_SERVER__ENDPOINTS+`,"`+NULL+`","GitLab endpoints used for factory integrations. Comma separated list of GitLab server URLs or NULL if no integration expected." 
- `+CHE_INTEGRATION_GITLAB_OAUTH__ENDPOINT+`,"`+NULL#+`","Address of the GitLab server with configured OAuth 2 integration" 
+ `+CHE_INTEGRATION_GITLAB_OAUTH__ENDPOINT+`,"`+NULL+`","Address of the GitLab server with configured OAuth 2 integration" 
+ `+CHE_OAUTH2_GITLAB_CLIENTID__FILEPATH+`,"`+NULL+`","Configuration of GitLab OAuth2 client. Used to obtain Personal access tokens. Location of the file with GitLab client id." 
+ `+CHE_OAUTH2_GITLAB_CLIENTSECRET__FILEPATH+`,"`+NULL#+`","Location of the file with GitLab client secret." 
 ,=== 
 
 [id="che-system"]

modules/user-guide/nav.adoc

@@ -2,16 +2,19 @@ pass:[<!-- vale off -->]
 
 .User Guide
 
-//Part I for UX-optimized flows
 * xref:user-onboarding.adoc[]
-** projects-with-git.adoc
-** projects-without-git.adoc
-*** xref:starting-a-workspace.adoc[]
-**** xref:starting-a-workspace-using-the-dashboard.adoc[]
-**** xref:starting-a-workspace-using-an-url.adoc[]
-*** xref:defining-a-workspaces.adoc[]
+** xref:che-urls.adoc[]
+*** xref:url-of-your-organizations-che-instance.adoc[]
+*** xref:url-of-your-che-dashboard.adoc[]
+*** xref:urls-for-starting-a-new-workspace.adoc[]
+*** xref:urls-of-your-workspaces.adoc[]
+** xref:starting-a-new-workspace-with-a-clone-of-a-git-repository.adoc[]
+** xref:starting-a-stopped-workspace.adoc[]
 
-//Part II for advanced features and alternative settings not documented in Part I
-* xref:advanced-use.adoc
-//** xref:etc.adoc[]
-//** xref:etc.adoc[]
+* xref:advanced-use.adoc[]
+** xref:parameters-for-the-urls-for-starting-a-new-workspace.adoc[]
+*** xref:url-parameter-concatenation.adoc[]
+*** xref:url-parameter-for-the-workspace-ide.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[]

modules/user-guide/pages/advanced-use.adoc

@@ -1,8 +1,8 @@
-:_content-type: assembly
-:description: Advanced Use
+:_content-type: CONCEPT
+:description: Advanced use
 :keywords: advanced-use, advanced-user, advanced-users, user-guide
-:navtitle: Advanced Use
+:navtitle: Advanced use
 // :page-aliases:
 
 [id="advanced-use_{context}"]
-= Advanced Use
+= Advanced use

modules/user-guide/pages/che-urls.adoc

@@ -0,0 +1,15 @@
+:_content-type: CONCEPT
+:description: {prod-short} URLs
+:keywords: url, dashboard, {prod-short}, workspace, workspaces, new-workspace, your-workspace
+:navtitle: {prod-short} URLs
+// :page-aliases:
+
+[id="{prod-id-short}-urls_{context}"]
+= {prod-short} URLs
+
+Working with {prod-short} involves regular use of the following URLs:
+
+* xref:url-of-your-organizations-che-instance.adoc[]
+* xref:url-of-your-che-dashboard.adoc[]
+* xref:urls-for-starting-a-new-workspace.adoc[]
+* xref:urls-of-your-workspaces.adoc[]

modules/user-guide/pages/parameters-for-the-urls-for-starting-a-new-workspace.adoc

@@ -0,0 +1,14 @@
+:_content-type: CONCEPT
+:description: Parameters for the URLs for starting a new workspace
+:keywords: url, urls, parameter, parameters, starting, start, workspace, workspaces
+:navtitle: Parameters for the URLs for starting a new workspace
+// :page-aliases:
+
+[id="parameters-for-the-urls-for-starting-a-new-workspace_{context}"]
+= Parameters for the URLs for starting a new workspace
+
+* xref:url-parameter-for-the-workspace-ide.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-concatenation.adoc[]

modules/user-guide/pages/starting-a-new-workspace-with-a-clone-of-a-git-repository.adoc

@@ -0,0 +1,42 @@
+:_content-type: PROCEDURE
+:description: Starting a new workspace with a clone of a Git repository
+: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 new workspace with a clone of a Git repository
+// :page-aliases:
+
+[id="starting-a-new-workspace-with-a-clone-of-a-git-repository_{context}"]
+= Starting a new workspace with a clone of a Git repository
+
+With {prod-short}, you can start a new workspace that contains a clone of a Git repository. So you can have your remote origin or fork cloned into a new starting workspace. Or you can have a common repository of a project cloned into a new starting workspace. With such Git providers as GitHub and GitLab, you can also specify the branch for the new starting workspace to checkout.
+
+TIP: Advanced users can compose and use their own devfiles, as well as use a local devfile.
+//provide links on "compose", "devfiles", and "local devfile" to the corresponding sections in Advanced Use (User Guide). max-cx
+
+IMPORTANT: Although the devfile enables full functionality of a workspace, you can also start a new workspace by supplying the URL of a Git repository without a devfile. This results in a new workspace with a clone of the Git repository and with the defaults such as the Che-Theia IDE and the Universal Developer Image.
+//provide xrefs to a concept module about the Universal Developer Image and, if applicable, devfile-less defaults for new workspaces. max-cx
+
+NOTE: The *Create Workspace* page of your {prod-short} xref:url-of-your-che-dashboard.adoc[dashboard] has the *Git Repo URL ** field as the GUI alternative for entering the URL of a Git repository to start a new workspace.
+
+.Prerequisites
+
+* Your organization has a running instance of {prod-short}.
+* You have been given the xref:url-of-your-organizations-che-instance.adoc[].
+* Your Git repository maintainer keeps the `devfile.yaml` or `.devfile.yaml` file in the root directory of the Git repository.
+* Optional: Private repositories that are hosted on GitHub, GitLab, or Bitbucket require (1) an authorized application link to be created on the repository-hosting website by the repository maintainer (which is you for your fork) and (2) a {platforms-name} secret to be applied by the administrator of the {prod-short} instance that belongs to your organization.
+//two inline links to be added into this par in the next, separate PR. max-cx
+
+.Procedure
+
+. Optional: visit the xref:url-of-your-che-dashboard.adoc[] to log in as a {prod-short} user to your organization's instance of {prod-short}.
+
+. Visit the xref:urls-for-starting-a-new-workspace.adoc[URL to start a new workspace].
++
+A new tab opens with the workspace-starting page in *Progress*.
++
+When the new workspace is ready, the workspace user interface loads in the browser tab.
++
+A clone of the Git repository is present in the filesystem of the new workspace.
+
+.Additional resources
+
+* xref:parameters-for-the-urls-for-starting-a-new-workspace.adoc[]

modules/user-guide/pages/starting-a-stopped-workspace.adoc

@@ -0,0 +1,38 @@
+:_content-type: PROCEDURE
+:description: Starting a stopped workspace
+:keywords: start-stopped-workspace, start-a-stopped-workspace, starting-a-stopped-workspace, starting-stopped-workspace, stopped-workspace, how-to-start-workspace, how-to-start-a-workspace
+:navtitle: Starting a stopped workspace
+// :page-aliases:
+
+[id="starting-a-stopped-workspace_{context}"]
+= Starting a stopped workspace
+
+You can start a stopped workspace by using the {prod-short} dashboard.
+//todo: link `stopped` to my draft of stopping-a-running-workspace.adoc. max-cx
+
+.Procedure
+
+To start and open a stopped workspace in a new tab:
+
+. Go to the xref:url-of-your-che-dashboard.adoc[*Workspaces*] page of your {prod-short} dashboard.
+
+. Locate the workspace in the list.
+
+. Click *Open*.
++
+A new tab opens with the workspace-starting page in *Progress*.
++
+When the new workspace is ready, the workspace user interface loads in the browser tab.
+
+[TIP]
+====
+Starting a stopped workspace when you still have the browser tab for it in your browser:
+
+. In another tab in the browser, go to the xref:url-of-your-che-dashboard.adoc[*Workspaces*] page of your {prod-short} dashboard.
+
+. Locate the workspace in the list.
+
+. Go to *⋮* *>* *Start in Background*.
+
+. Reload or refresh the browser tab of the workspace: kbd:[Ctrl+R] in Mozilla Firefox or Google Chrome.
+====

modules/user-guide/pages/url-of-your-che-dashboard.adoc

@@ -0,0 +1,21 @@
+:_content-type: CONCEPT
+:description: URL of your {prod-short} dashboard
+:keywords: dashboard, manage-workspaces, verify, workspace-status, workspace-state
+:navtitle: URL of your {prod-short} dashboard
+// :page-aliases:
+
+[id="url-of-your-{prod-id-short}-dashboard_{context}"]
+= URL of your {prod-short} dashboard
+
+The *Workspaces* page of your {prod-short} dashboard is where you manage your workspaces and verify their current states. The URL syntax for this page is like so:
+
+[source,subs="+quotes,+attributes"]
+----
+{prod-url}/dashboard/#/workspaces
+----
+
+include::partial$snip_bookmark-this-url-in-your-browser-for-convenience.adoc[]
+
+.Additional resources
+
+* xref:url-of-your-organizations-che-instance.adoc[]

modules/user-guide/pages/url-of-your-organizations-che-instance.adoc

@@ -0,0 +1,15 @@
+:_content-type: CONCEPT
+:description: URL of your organization's {prod-short} instance
+:keywords: team, organization, organization-url, url-organization, fqdn, fully-qualified-domain-name
+:navtitle: URL of your organization's {prod-short} instance
+// :page-aliases:
+
+[id="url-of-your-organizations-{prod-id-short}-instance_{context}"]
+= URL of your organization's {prod-short} instance
+
+Your {prod-short} administrator must provide you with the URL of your organization's {prod-short} instance that you need as a user to access your {prod-short} dashboard and start and manage your workspaces. This URL is a fully qualified domain name (FQDN):
+
+[source,subs="+quotes,+attributes"]
+----
+{prod-url}
+----

modules/user-guide/pages/url-parameter-concatenation.adoc

@@ -0,0 +1,20 @@
+:_content-type: CONCEPT
+:description: URL parameter concatenation
+:keywords: url-parameters, multiple-url-parameters, combine-url-parameters, several-url-parameters, add-url-parameters, concatenate, concatenate-multiple-URL-parameters, concatenate-URL-parameters, concatenating, concatenating-multiple-URL-parameters, concatenating-URL-parameters, concatenation
+:navtitle: URL parameter concatenation
+// :page-aliases:
+
+[id="url-parameter-concatenation_{context}"]
+= URL parameter concatenation
+
+The xref:urls-for-starting-a-new-workspace.adoc[URL for starting a new workspace] supports concatenation of multiple URL parameters by using `&` with the following URL syntax:
+
+[source,subs="+quotes,+attributes"]
+----
+{prod-url}#__<git_repository_url>__?__<url_parameter_1>__&__<url_parameter_2>__&__<url_parameter_3>__
+----
+
+TIP: Remember to add `?` as a prefix to the first URL parameter after the URL of the linked Git repository.
+
+.Additional resources
+* xref:starting-a-new-workspace-with-a-clone-of-a-git-repository.adoc[]

modules/user-guide/pages/url-parameter-for-starting-duplicate-workspaces.adoc

@@ -0,0 +1,23 @@
+:_content-type: CONCEPT
+:description: URL parameter for starting duplicate workspaces
+:keywords: start-duplicate-workspaces, start-duplicated-workspaces, duplicate-workspace, duplicate-workspaces, duplicated-workspace, duplicated-workspaces, how-to-start-a-duplicate, how-to-start-duplicate
+:navtitle: URL parameter for starting duplicate workspaces
+// :page-aliases:
+
+[id="url-parameter-for-starting-duplicate-workspaces_{context}"]
+= URL parameter for starting duplicate workspaces
+
+Visiting a URL for starting a new workspace results in a workspace that is based on a combination of a devfile and a linked Git repository.
+
+In some situations, you may need to start one or more workspaces from the same URL for starting a new workspace, resulting in workspaces that are duplicates in terms of the same devfile and the same linked Git repository. The URL parameter for starting a duplicate workspace is `new`. The URL for starting a new workspace has the following syntax with the `new` parameter:
+
+[source,subs="+quotes,+attributes"]
+----
+{prod-url}#__<git_repository_url>__?new
+----
+
+NOTE: Attempting to reuse the devfile and linked Git repository without the `new` URL parameter to start a new workspace in addition to a workspace that already exists results in an error message.
+
+.Additional resources
+* xref:urls-for-starting-a-new-workspace.adoc[]
+* xref:starting-a-new-workspace-with-a-clone-of-a-git-repository.adoc[]