docs: review and edits of PR #2510 docs: manage workspaces with kubectl

modules/end-user-guide/pages/managing-workspaces-with-apis.adoc

@@ -7,16 +7,14 @@
 [id="managing-workspaces-with-apis"]
 = Managing workspaces with {orch-name} APIs
 
-On a {platforms-name} cluster, {prod-short} workspaces are represented as `DevWorkspace` custom resources of the same name.
-As a result, if there is a workspace named `my-workspace` in the {prod-short} dashboard, there is a `DevWorkspace` named `my-workspace` in the user's {orch-namespace} on the {orch-name} cluster.
+On your organization's {orch-name} cluster, {prod-short} workspaces are represented as `DevWorkspace` custom resources of the same name.
+As a result, if there is a workspace named `my-workspace` in the {prod-short} dashboard, there is a corresponding `DevWorkspace` custom resource named `my-workspace` in the user's {orch-namespace} on the cluster.
 
-Since `DevWorkspaces` on the cluster represent {prod-short} workspaces, this allows managing {prod-short} workspaces using {orch-name} APIs with clients such as {orch-cli}.
+Because each `DevWorkspace` custom resource on the cluster represents a {prod-short} workspace, you can manage {prod-short} workspaces by using {orch-name} APIs with clients such as the command-line `{orch-cli}`.
 
-Each `DevWorkspace` contains details derived from the workspace project's devfile, such as workspace container configurations and devfile commands.
+Each `DevWorkspace` contains details derived from the devfile of the Git repository cloned for the workspace. For example, a devfile might provide devfile commands and workspace container configurations.
 
-Each `DevWorkspace` also references a `DevWorkspaceTemplate` custom resource using the `spec.contributions` field, which contains details about the editor for the workspace.
-
-To manage a workspace with {orch-name} APIs, you must determine the workspace `NAME` and the `NAMESPACE` it is located in.
+Each `DevWorkspace` custom resource also references a `DevWorkspaceTemplate` custom resource using the `spec.contributions` field, which provides details about the IDE for the workspace.
 
 include::partial$proc_listing-workspaces.adoc[leveloffset=+1]
 

modules/end-user-guide/partials/proc_creating-workspaces.adoc

@@ -2,38 +2,60 @@
 [id="creating-workspaces"]
 = Creating workspaces
 
-Since workspaces on the {orch-name} cluster are represented by custom resources, it is possible to create workspaces with {orch-name} APIs by applying custom resources to the cluster.
+If your use case does not permit use of the {prod-short} dashboard, you can create workspaces with {orch-name} APIs by applying custom resources to the cluster.
 
-It is recommended however, for users to create workspaces using the {prod-short} Dashboard instead of using {orch-name} APIs to manually create `DevWorkspace` and `DevWorkspaceTemplate` custom resources.
+[NOTE]
+====
 
-This is because creating workspaces using the {prod-short} Dashboard helps {prod-short} and its components convert the workspace project's devfile to `DevWorkspace` and `DevWorkspaceTemplate` custom resources on the cluster.
-
-Creating workspaces using the {prod-short} Dashboard allows {prod-short} to make the following additions to the newly created `DevWorkspaces`:
+Using the {prod-short} dashboard is the default way to create workspaces because {prod-short} and its components automatically convert the target Git repository's devfile into the `DevWorkspace` and `DevWorkspaceTemplate` custom resources on the cluster with the following configuration benefits:
 
 * Recognition of configurations in `spec.devEnvironments` specified in the `CheCluster` custom resource including:
-** persistent storage strategy specified with `devEnvironments.storage`
-** default editor specified with `devEnvironments.defaultEditor`
-** default plugins specified with `devEnvironments.defaultPlugins`
-** container build configuration specified with `devEnvironments.containerBuildConfiguration`
+** Persistent storage strategy specified with `devEnvironments.storage`
+** Default IDE specified with `devEnvironments.defaultEditor`
+** Default plugins specified with `devEnvironments.defaultPlugins`
+** Container build configuration specified with `devEnvironments.containerBuildConfiguration`
 * Recognition of the `DevWorkspaceOperatorConfig` configuration managed by {prod-short}
 
+====
+
 .Prerequisites
 
-* An active `{orch-cli}` session with permissions to create `DevWorkspace` and `DevWorkspaceTemplate` resources in your {orch-namespace} on the {orch-name} cluster. See {orch-cli-link}.
+* An active `{orch-cli}` session with permissions to create `DevWorkspace` and `DevWorkspaceTemplate` resources in your {orch-namespace} on the cluster. See {orch-cli-link}.
+
+* You know the relevant {prod-short} user namespace on the cluster.
++
+TIP: You can visit `pass:c,a,q[{prod-url}]/api/kubernetes/namespace` to get your {prod-short} user namespace as `name`.
 
-NOTE: For admins creating workspaces for users, the `DevWorkspace` and `DevWorkspaceTemplate` custom resources should be created in a user namespace that is provisioned by {prod-short} or provisioned by the admin. See xref:administration-guide:configuring-namespace-provisioning.adoc[].
+* You are on the {prod-short} user namespace on the cluster.
++
+[TIP]
+====
+On OpenShift:
+
+* You can use the `oc` command-line tool to check your current namespace:
++
+`$ oc project`
+
+* You can switch to your {prod-short} user namespace on a command line if needed:
++
+`$ oc project __<user_namespace>__`
+====
++
+NOTE: {prod-short} administrators who intend to create workspaces for other users must create the `DevWorkspace` and `DevWorkspaceTemplate` custom resources in a user namespace that is provisioned by {prod-short} or by the administrator. See xref:administration-guide:configuring-namespace-provisioning.adoc[].
 
 .Procedure
 
-. Create a `DevWorkspaceTemplate` for the editor. The example below creates a `DevWorkspaceTemplate` named `che-code` for the Che-Code Visual Studio Code editor.
+. Create a `DevWorkspaceTemplate` custom resource for the selected IDE.
 +
+.Creating a `DevWorkspaceTemplate` named `che-code` for the link:https://github.com/microsoft/vscode[Microsoft Visual Studio Code - Open Source] IDE
+====
 [source,yaml,subs="+quotes,+attributes"]
 ----
 apiVersion: workspace.devfile.io/v1alpha2
 kind: DevWorkspaceTemplate
 metadata:
-  name: che-code <1>
-  namespace: __<user_{orch-namespace}>__ <2>
+  name: che-code#<1>
+  namespace: user1-dev#<2>
 spec:
   commands:
     - apply:
@@ -70,7 +92,7 @@ spec:
           - name: checode
             path: /checode
         memoryLimit: 1024Mi
-        image: 'quay.io/che-incubator/che-code:insiders' # no-op ignored image
+        image: 'quay.io/che-incubator/che-code:insiders'
         endpoints:
           - attributes:
               cookiesAuthEnabled: true
@@ -111,68 +133,92 @@ spec:
     preStart:
       - init-container-command
 ----
-<1> Name of the `DevWorkspaceTemplate`. This name will be used to reference the `DevWorkspaceTemplate` within the `DevWorkspace`.
-<2> Target {orch-namespace} for the new workspace.
-. To prepare the `DevWorkspace` custom resource, copy the contents of a project Devfile. The example used for this procedure is the following Devfile:
+<1> Name of the `DevWorkspaceTemplate` custom resource. This name will be used to reference the `DevWorkspaceTemplate` custom resource within the `DevWorkspace` custom resource.
+<2> User namespace, which is the target {orch-namespace} for the new workspace.
+====
+
+. To prepare the `DevWorkspace` custom resource, copy the contents of the target Git repository's devfile.
 +
+.Copied devfile contents with `schemaVersion: 2.1.0`
+====
 [source,yaml,subs="+quotes,+attributes"]
 ----
-schemaVersion: 2.1.0    
 components:
   - name: tooling-container
     container:
       image: quay.io/devfile/universal-developer-image:ubi8-latest
 ----
+====
 +
-For more details about Devfiles, see the link:https://devfile.io/docs/2.1.0/what-is-a-devfile[Devfile v2 documentation].
+TIP: For more details, see the link:https://devfile.io/docs/2.1.0/what-is-a-devfile[devfile v2 documentation].
 
-. Use the Devfile to create a `DevWorkspace` definition.
+. Create a `DevWorkspace` custom resource definition, pasting the devfile contents from the previous step under the `spec.template` field.
 +
+.A `DevWorkspace` custom resource definition
+====
 [source,yaml,subs="+quotes,+attributes"]
 ----
 kind: DevWorkspace
 apiVersion: workspace.devfile.io/v1alpha2
 metadata:
-  name: my-devworkspace <1>
-  namespace: __<user_{orch-namespace}>__ <2>
+  name: my-devworkspace#<1>
+  namespace: user1-dev#<2>
 spec:
-  started: true <3>
-  contributions: <4>
-    - name: editor
+  started: true#<3>
+  contributions:#<4>
+    - name: IDE
       kubernetes:
-        name: che-code <5>
+        name: che-code#<5>
   template:
-    projects: <6>
+    projects:#<6>
       - name: my-project-name
         git:
           remotes:
             origin: https://github.com/eclipse-che/che-docs
-    components: <7>
+    components:#<7>
       - name: tooling-container
         container:
           image: quay.io/devfile/universal-developer-image:ubi8-latest
 ----
-<1> Name of `DevWorkspace` resource. This is will be the name of the new workspace.
-<2> Target {orch-namespace} for the new workspace.
-<3> Determines whether the workspace should be started upon creating the `DevWorkspace` resource.
-<4> Reference to the editor's `DevWorkspaceTemplate`.
-<5> Name of the editor's `DevWorkspaceTemplate` from the previous step.
-<6> Details about the Git project to clone upon workspace startup. The Git project that will be cloned for this example is https://github.com/eclipse-che/che-docs.
+<1> Name of the `DevWorkspace` custom resource. This is will be the name of the new workspace.
+<2> User namespace, which is the target {orch-namespace} for the new workspace.
+<3> Determines whether the workspace must be started when the `DevWorkspace` custom resource is created.
+<4> Reference to the `DevWorkspaceTemplate` custom resource of the selected IDE.
+<5> Name of the `DevWorkspaceTemplate` custom resource from the previous step.
+<6> Details about the Git repository to clone into the workspace when it starts.
 <7> List of components such as workspace containers and volume components.
-. Apply the `DevWorkspace` to the cluster. 
-. Confirm that the workspace is starting by referring to the `PHASE` status of the `DevWorkspace`.
+====
+
+. Apply the `DevWorkspace` custom resource to the cluster. 
+
+. Verify that the workspace is starting by checking the *PHASE* status of the `DevWorkspace`.
 +
 [subs="+quotes,attributes"]
 ----
 $ {orch-cli} get devworkspaces -n __<user_{orch-namespace}>__  --watch
-
+----
++
+.Output
+====
+[subs="+quotes,attributes"]
+----
 NAMESPACE            NAME                  DEVWORKSPACE ID             PHASE      INFO
-__<user_{orch-namespace}>__   my-devworkspace       workspacedf64e4a492cd4701   Starting   Waiting for workspace deployment
+user1-dev	     my-devworkspace       workspacedf64e4a492cd4701   Starting   Waiting for workspace deployment
 ----
-. Once the workspace starts, the workspace can be opened by accessing the URL provided in the `INFO` section of the output from `{orch-cli} get devworkspaces`, or by accessing the workspace from the {prod-short} Dashboard.
+====
+
+. When the workspace has successfully started, its *PHASE* status changes to *Running* in the output of the `{orch-cli} get devworkspaces` command.
 +
+.Output
+====
 [subs="+quotes,attributes"]
 ----
 NAMESPACE            NAME                  DEVWORKSPACE ID             PHASE      INFO
-__<user_{orch-namespace}>__   my-devworkspace       workspacedf64e4a492cd4701   Running    https://url-to-workspace.com
+user1-dev	     my-devworkspace       workspacedf64e4a492cd4701   Running    https://url-to-workspace.com
 ----
+====
++
+You can then open the workspace by using one of these options:
++
+** Visit the URL provided in the `INFO` section of the output of the `{orch-cli} get devworkspaces` command.
+** Open the workspace from the {prod-short} dashboard.

modules/end-user-guide/partials/proc_listing-workspaces.adoc

@@ -2,28 +2,56 @@
 [id="listing-workspaces"]
 = Listing all workspaces
 
-Run the following command to list all workspaces for all users.
+You can list your workspaces on a command line.
 
-[source,subs="+attributes"]
-----
-$ {orch-cli} get devworkspaces
+.Prerequisites
 
-NAMESPACE   NAME                 DEVWORKSPACE ID             PHASE     INFO
-user1-dev   golang-example       workspacedf64e4a492cd4701   Stopped   Stopped
-user1-dev   php-symfony          workspace5a8f37a0a0d94ea3   Stopped   Stopped
-----
+* An active `{orch-cli}` session on the cluster. See {orch-cli-link}.
+
+* You know the relevant {prod-short} user namespace on the cluster.
++
+TIP: You can visit `pass:c,a,q[{prod-url}]/api/kubernetes/namespace` to get your {prod-short} user namespace as `name`.
+
+* You are on the {prod-short} user namespace on the cluster.
++
+[TIP]
+====
+On OpenShift:
 
-TIP: You can add the `--watch` flag to view updates when the workspace's `PHASE` changes.
+* You can use the `oc` command-line tool to check your current namespace:
++
+`$ oc project`
 
-Admins can add the `--all-namespaces` flag to list all workspaces from all users.
+* You can switch to your {prod-short} user namespace on a command line if needed:
++
+`$ oc project __<user_namespace>__`
+====
 
+.Procedure
+
+* To list your workspaces, enter the following on a command line:
++
 [source,subs="+attributes"]
 ----
-$ {orch-cli} get devworkspaces --all-namespaces
-
+$ {orch-cli} get devworkspaces
+----
++
+.Output
+====
+----
 NAMESPACE   NAME                 DEVWORKSPACE ID             PHASE     INFO
+user1-dev   spring-petclinic     workspace6d99e9ffb9784491   Running   https://url-to-workspace.com
 user1-dev   golang-example       workspacedf64e4a492cd4701   Stopped   Stopped
-user1-dev   php-symfony          workspace5a8f37a0a0d94ea3   Stopped   Stopped
-user2-dev   python-hello-world   workspace69c26884bbc141f2   Failed    Container tooling has state CrashLoopBackOff
-user3-dev   spring-petclinic     workspace6d99e9ffb9784491   Running   https://url-to-workspace.com
+user1-dev   python-hello-world   workspace69c26884bbc141f2   Failed    Container tooling has state CrashLoopBackOff
 ----
+====
+
+[TIP]
+====
+You can view *PHASE* changes live by adding the `--watch` flag to this command.
+====
+
+[NOTE]
+====
+Users with administrative permissions on the cluster can list all workspaces from all {prod-short} users by including the `--all-namespaces` flag.
+====

modules/end-user-guide/partials/proc_removing-workspaces.adoc

@@ -2,11 +2,49 @@
 [id="removing-workspaces"]
 = Removing workspaces
 
-Removing a workspace only requires deleting the `DevWorkspace` custom resource.
+You can remove a workspace by simply deleting the `DevWorkspace` custom resource.
 
-Deleting the `DevWorkspace` custom resource will also delete other workspace resources if they were created by {prod-short} such as the referenced `DevWorkspaceTemplate` and per-workspace `PersistentVolumeClaims`.
+WARNING: Deleting the `DevWorkspace` custom resource will also delete other workspace resources if they were created by {prod-short}: for example, the referenced `DevWorkspaceTemplate` and per-workspace `PersistentVolumeClaims`.
 
-[source,subs="+attributes"]
+TIP: Remove workspaces by using the {prod-short} dashboard whenever possible.
+
+.Prerequisites
+
+* An active `{orch-cli}` session on the cluster. See {orch-cli-link}.
+
+* You know the workspace name.
++
+[TIP]
+====
+You can find the relevant workspace name in the output of the following command:
+
+`$ {orch-cli} get devworkspaces`
+====
+
+* You know the relevant {prod-short} user namespace on the cluster.
++
+TIP: You can visit `pass:c,a,q[{prod-url}]/api/kubernetes/namespace` to get your {prod-short} user namespace as `name`.
+
+* You are on the {prod-short} user namespace on the cluster.
++
+[TIP]
+====
+On OpenShift:
+
+* You can use the `oc` command-line tool to check your current namespace:
++
+`$ oc project`
+
+* You can switch to your {prod-short} user namespace on a command line if needed:
++
+`$ oc project __<user_namespace>__`
+====
+
+.Procedure
+
+* Run the following command to remove the workspace:
++
+[subs="+quotes,attributes"]
 ----
-$ {orch-cli} delete devworkspace NAME -n NAMESPACE
+$ {orch-cli} delete devworkspace __<workspace_name>__ -n __<user_namespace>__
 ----