docs: user onboarding, starting a new workspace, URL parameters

modules/end-user-guide/nav.adoc

@@ -1,5 +1,9 @@
 .User Guide
 
+* xref:user-onboarding.adoc[]
+** xref:starting-a-new-workspace-with-a-clone-of-a-git-repository.adoc[]
+** xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[]
+** xref:basic-actions-you-can-perform-on-a-workspace.adoc[]
 * xref:using-developer-workspaces.adoc[]
 ** xref:first-time-contributors.adoc[]
 ** xref:benefits-of-pull-requests-review-in-che.adoc[]

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

@@ -0,0 +1,33 @@
+:_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:
+
+[id="basic-actions-you-can-perform-on-a-workspace_{context}"]
+= Basic actions you can perform on a workspace
+
+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.
+
+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
+|===
+| Action | GUI steps in the Workspaces page
+
+| _Reopen a running workspace_
+| Click *Open*.
+
+| _Restart a running workspace_
+| Go to *⋮* *>* *Restart Workspace*.
+
+| _Stop a running workspace_
+| Go to *⋮* *>* *Stop Workspace*.
+
+| _Start a stopped workspace_
+| Click *Open*.
+
+| _Delete a workspace_
+| Go to *⋮* *>* *Delete Workspace*.
+
+|===

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

@@ -0,0 +1,136 @@
+:_content-type: CONCEPT
+:description: Optional parameters for the URLs for starting a new workspace
+:keywords: url, urls, parameter, parameters, starting, start, workspace, workspaces, url-parameter, 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, start-duplicate-workspaces, start-duplicated-workspaces, duplicate-workspace, duplicate-workspaces, duplicated-workspace, duplicated-workspaces, how-to-start-a-duplicate, how-to-start-duplicate, devfile, override-devfile-file-name, override-file-name, file-name, devfile-name, different-devfile-name, file-path, devfile-path, devfile-file-path, devfile-path-parameter, devfile-file-path-parameterdevfile, file-path, devfile-path, devfile-file-path, devfile-path-parameter, devfile-file-path-parameter
+:navtitle: Optional parameters for the URLs for starting a new workspace
+// :page-aliases:
+
+[id="parameters-for-the-urls-for-starting-a-new-workspace_{context}"]
+= Optional parameters for the URLs for starting a new workspace
+
+When you start a new workspace, {prod-short} configures the workspace according to the instructions in the devfile. When you use a URL to start a new workspace, you can append optional parameters to the URL that further configure the workspace. You can use these parameters to specify a workspace IDE, start duplicate workspaces, and specify a devfile file name or path.
+
+== URL parameter concatenation
+
+The URL for starting a new workspace supports concatenation of multiple optional URL parameters by using `&` with the following URL syntax:
+
+`pass:c,a,q[{prod-url}]#__<git_repository_url>__?__<url_parameter_1>__&__<url_parameter_2>__&__<url_parameter_3>__`
+
+.A URL for starting a new workspace with the URL of a Git repository and optional URL parameters
+====
+The complete URL for the browser:
+
+ifeval::["{project-context}" == "crw"]
+`\https://codeready-codeready-workspaces-operator.apps.sandbox-m2.ll9k.p1.openshiftapps.com#https://github.com/che-samples/cpp-hello-world?new&che-editor=che-incubator/intellij-community/latest&devfilePath=tests/testdevfile.yaml`
+endif::[]
+
+ifeval::["{project-context}" == "che"]
+`\https://che-openshift-operators.apps.ci-ln-yp1cppt-72292.origin-ci-int-gce.dev.rhcloud.com#https://github.com/che-samples/cpp-hello-world?new&che-editor=che-incubator/intellij-community/latest&devfilePath=tests/testdevfile.yaml`
+endif::[]
+
+Explanation of the parts of the URL:
+
+[source,subs="+quotes,+attributes,+macros"]
+----
+ifeval::["{project-context}" == "che"]
+\https://che-openshift-operators.apps.ci-ln-yp1cppt-72292.origin-ci-int-gce.dev.rhcloud.com/ <1>
+endif::[]
+ifeval::["{project-context}" == "crw"]
+\https://codeready-codeready-workspaces-operator.apps.sandbox-m2.ll9k.p1.openshiftapps.com <1>
+endif::[]
+#https://github.com/che-samples/cpp-hello-world <2>
+?new&che-editor=che-incubator/intellij-community/latest&devfilePath=tests/testdevfile.yaml <3>
+----
+<1> The pass:c,a,q[{prod-url}] part of the URL.
+<2> The URL of the Git repository to be cloned into the new workspace.
+<3> The concatenated optional URL parameters.
+====
+
+== URL parameter for the workspace IDE
+
+Che-Theia is the default integrated development environment (IDE) that a workspace loads with if no IDE is specified as a URL parameter as part of the URL for starting a new workspace.
+
+The URL parameter for specifying another supported IDE is `che-editor=__<editor_key>__`:
+
+[source,subs="+quotes,+attributes,+macros"]
+----
+pass:c,a,q[{prod-url}]#__<git_repository_url>__?che-editor=__<editor_key>__
+----
+
+.The `__<editor_key>__` values for the supported IDEs
+|===
+| IDE | `__<editor_key>__` value | Note
+
+ifeval::["{project-context}" == "che"]
+| link:https://github.com/eclipse-che/che-theia[Che-Theia]
+| `eclipse/che-theia/latest`
+| When using the `stable` link:https://github.com/che-incubator/chectl/[chectl] channel, this IDE loads as a default without this URL parameter.
+
+| link:https://github.com/eclipse-che/che-theia[Che-Theia]
+| `eclipse/che-theia/next`
+| When using the `next` link:https://github.com/che-incubator/chectl/[chectl] channel, this IDE loads as a default without this URL parameter.
+endif::[]
+
+ifeval::["{project-context}" == "crw"]
+| link:https://github.com/eclipse-che/che-theia[Che-Theia]
+|`eclipse/che-theia/latest`
+| This is the default IDE that loads in a new workspace without this URL parameter.
+endif::[]
+
+| link:https://github.com/che-incubator/che-code[Che-Code]
+| `che-incubator/che-code/insiders`
+|
+
+| link:https://www.jetbrains.com/help/idea/discover-intellij-idea.html[IntelliJ IDEA Community Edition]
+| `che-incubator/intellij-community/latest`
+|
+
+| link:https://www.jetbrains.com/help/pycharm/quick-start-guide.html[PyCharm]
+| `che-incubator/pycharm/latest`
+|
+
+|===
+
+== URL parameter for starting duplicate workspaces
+
+Visiting a URL for starting a new workspace results in a new workspace according to the devfile and with a clone of the linked Git repository.
+
+In some situations, you may need to have multiple workspaces that are duplicates in terms of the devfile and the linked Git repository. You can do this by visiting the same URL for starting a new workspace with a URL parameter.
+
+The URL parameter for starting a duplicate workspace is `new`:
+
+[source,subs="+quotes,+attributes,+macros"]
+----
+pass:c,a,q[{prod-url}]#__<git_repository_url>__?new
+----
+
+NOTE: If you currently have a workspace that you started using a URL, then visiting the URL again without the `new` URL parameter results in an error message.
+
+== URL parameter for the devfile file name
+
+When you visit a URL for starting a new workspace, {prod-short} searches the linked Git repository for a devfile with the file name `.devfile.yaml` or `devfile.yaml`. The devfile in the linked Git repository must follow this file-naming convention.
+
+In some situations, you may need to specify a different, unconventional file name for the devfile.
+
+The URL parameter for specifying an unconventional file name of the devfile is `df=__<filename>__.yaml`:
+
+[source,subs="+quotes,+attributes,+macros"]
+----
+pass:c,a,q[{prod-url}]#__<git_repository_url>__?df=__<filename>__.yaml <1>
+----
+<1> `__<filename>__.yaml` is an unconventional file name of the devfile in the linked Git repository.
+
+TIP: The `df=__<filename>__.yaml` parameter also has a long version: `devfilePath=__<filename>__.yaml`.
+
+== URL parameter for the devfile file path
+
+When you visit a URL for starting a new workspace, {prod-short} searches the root directory of the linked Git repository for a devfile (with the file name `.devfile.yaml` or `devfile.yaml`). The file path of the devfile in the linked Git repository must follow this path convention.
+
+In some situations, you may need to specify a different, unconventional file path for the devfile in the linked Git repository.
+
+The URL parameter for specifying an unconventional file path of the devfile is `devfilePath=__<relative_file_path>__`:
+
+[source,subs="+quotes,+attributes,+macros"]
+----
+pass:c,a,q[{prod-url}]#__<git_repository_url>__?devfilePath=__<relative_file_path>__ <1>
+----
+<1> `__<relative_file_path>__` is an unconventional file path of the devfile in the linked Git repository.

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

@@ -0,0 +1,95 @@
+:_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
+
+Working with {prod-short} in your browser involves multiple URLs:
+
+* The URL of your organization's {prod-short} instance, used as part of all the following URLs
+* The URL of the *Workspaces* page of your {prod-short} dashboard with the workspace control panel
+* [.underline]#The URLs for starting a new workspace#
+* The URLs of your workspaces in use
+
+With {prod-short}, you can visit a URL in your browser to start a new workspace that contains a clone of a Git repository. This way, you can clone a Git repository that is hosted on GitHub, a GitLab instance, or a Bitbucket server.
+
+TIP: You can also use the *Git Repo URL ** field on the *Create Workspace* page of your {prod-short} dashboard to enter the URL of a Git repository to start a new workspace.
+
+.Prerequisites
+
+* 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}]`.
+* 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[].)
++
+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 the Che-Theia IDE and the Universal Developer Image.
+//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
+
+.Procedure
+
+To start a new workspace with a clone of a Git repository:
+
+. Optional: Visit your {prod-short} dashboard pages to authenticate to your organization's instance of {prod-short}.
+
+. Visit the URL to start a new workspace using the basic syntax:
+[source,subs="+quotes,+attributes,+macros"]
++
+----
+pass:c,a,q[{prod-url}]#__<git_repository_url>__
+----
++
+[TIP]
+====
+You can extend this URL with optional parameters:
+[source,subs="+quotes,+attributes,+macros"]
+----
+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[].
+====
++
+.A URL for starting a new workspace
+====
+
+ifeval::["{project-context}" == "che"]
+`\https://che-openshift-operators.apps.ci-ln-yp1cppt-72292.origin-ci-int-gce.dev.rhcloud.com#https://github.com/che-samples/cpp-hello-world`
+endif::[]
+ifeval::["{project-context}" == "crw"]
+`\https://codeready-codeready-workspaces-operator.apps.sandbox-m2.ll9k.p1.openshiftapps.com#https://github.com/che-samples/cpp-hello-world`
+endif::[]
+
+====
++
+.The URL syntax for starting a new workspace with a clone of a GitHub-hosted repository
+====
+
+With GitHub and GitLab, you can even use the URL of a specific branch of the repository to be cloned:
+
+* `pass:c,a,q[{prod-url}#https://github.com/__<user_or_org>__/__<repository>__]` starts a new workspace with a clone of the default branch.
+* `pass:c,a,q[{prod-url}#https://github.com/__<user_or_org>__/__<repository>__/tree/__<branch_name>__]` starts a new workspace with a clone of the specified branch.
+* `pass:c,a,q[{prod-url}#https://github.com/__<user_or_org>__/__<repository>__/pull/__<pull_request_id>__]` starts a new workspace with a clone of the branch of the pull request.
+====
++
+After you enter the URL to start a new workspace in a browser tab, it renders the workspace-starting page.
++
+When the new workspace is ready, the workspace IDE loads in the browser tab.
++
+A clone of the Git repository is present in the filesystem of the new workspace.
++
+The workspace has a unique URL: `pass:c,a,q[{prod-url}]#workspace__<unique_url>__`.
+
+[TIP]
+====
+Although this is not possible in the address bar, you can add a URL for starting a new workspace as a bookmark by using the browser bookmark manager:
+
+* In Mozilla Firefox, go to *☰* *>* *Bookmarks* *>* *Manage bookmarks Ctrl+Shift+O* *>* *Bookmarks Toolbar* *>* *Organize* *>* *Add bookmark*.
+
+* In Google Chrome, go to *⋮* *>* *Bookmarks* *>* *Bookmark manager* *>* *Bookmarks bar* *>* *⋮* *>* *Add new bookmark*.
+====
+
+.Additional resources
+
+* xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[]
+* xref:basic-actions-you-can-perform-on-a-workspace.adoc[]

modules/end-user-guide/pages/user-onboarding.adoc

@@ -0,0 +1,14 @@
+:_content-type: CONCEPT
+:description: User onboarding
+:keywords: getting-started, user-onboarding, new-user, new-users
+:navtitle: User onboarding
+// :page-aliases:
+
+[id="user-onboarding_{context}"]
+= User onboarding
+
+If your organization is already running a {prod-short} instance, you can get started as a new user of {prod-short} by first learning how to start a new workspace and how to manage your workspaces:
+
+. xref:starting-a-new-workspace-with-a-clone-of-a-git-repository.adoc[]
+. xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[]
+. xref:basic-actions-you-can-perform-on-a-workspace.adoc[]