Address PR feedback

Signed-off-by: dakwon <dakwon@redhat.com>

modules/end-user-guide/nav.adoc

@@ -14,7 +14,7 @@
 ** xref:mounting-configmaps.adoc[]
 ** xref:mounting-secrets.adoc[]
 *** xref:git-credential-store.adoc[]
-*** xref:image-pull-secrets.adoc[]
+** xref:image-pull-secrets.adoc[]
 * xref:integrating-with-kubernetes.adoc[]
 ** xref:automatic-token-injection.adoc[]
 ** xref:navigating-che-from-openshift-developer-perspective.adoc[]

modules/end-user-guide/pages/image-pull-secrets.adoc

@@ -5,22 +5,22 @@
 [id="image-pull-secrets_{context}"]
 = Creating image pull Secrets
 
-You can create an image pull Secret containing credentials to allow {devworkspace} Pods to access private container registries.
+You can create an image pull Secret containing credentials to allow {devworkspace} Pods to access container registries requiring authentication.
 
-An existing Docker credentials file such as `.dockercfg` or `$HOME/.docker/config.json` can be used to create the image pull Secret. Alternatively, the Secret can be created by running `{orch-cli} create secret docker-registry`.
+An existing Docker credentials file such as `.dockercfg` or `~/.docker/config.json` can be used to create the image pull Secret. Alternatively, the Secret can be created by running `{orch-cli} create secret docker-registry`.
 
 == Create an image pull Secret with an existing `.dockercfg` or `config.json` file
 
 .Prerequisites
 
 * A running instance of {prod-short}.
-* You have a `.dockercfg` or `$HOME/.docker/config.json` file containing credentials for the private container  registry.
+* You have a `.dockercfg` or `~/.docker/config.json` file containing credentials for the private container  registry.
 * You have GUI or CLI access to the {orch-name} cluster of your organization's {prod-short} instance.
 * For CLI users: The `{orch-cli}` and link:https://www.gnu.org/software/coreutils/base64[`base64`] command line tools are installed in the operating system you are using.
 
 .Procedure
 
-. Encode the `.dockercfg` or `$HOME/.docker/config.json` file to Base64. 
+. Encode the `.dockercfg` or `~/.docker/config.json` file to Base64. 
 +
 [TIP]
 ====
@@ -47,7 +47,7 @@ data:
 type: kubernetes.io/dockercfg
 ----
 
-* For `$HOME/.docker/config.json` create:
+* For `~/.docker/config.json` create:
 +
 [source,yaml,subs="+quotes,+attributes,+macros"]
 ----

modules/end-user-guide/pages/mounting-configmaps.adoc

@@ -5,19 +5,20 @@
 [id="mounting-configmaps_{context}"]
 = Mounting ConfigMaps
 
-You can automatically mount {orch-name} ConfigMaps to all {devworkspace} containers, creating permanent mount points for components such as configuration files (for example, the `settings.xml` file for Maven configuration).
+You can automatically mount {orch-name} ConfigMaps to all workspace containers, creating permanent mount points for components for configuration files.
 
 ConfigMaps are {orch-name} objects that store non-confidential data such as configuration values for an application.
 
 .Prerequisites
 
 * A running instance of {prod-short}.
 * You have GUI or CLI access to the {orch-name} cluster of your organization's {prod-short} instance.
+* You have created a new ConfigMap or determined an existing one in your user {orch-namespace} to mount to all workspaces containers.
 * For CLI users: The `{orch-cli}` command line tool is installed in the operating system you are using.
 
 .Procedure
 
-. Determine an existing ConfigMap or Secret in your user {orch-namespace} to mount to all {devworkspace} containers.
+. Determine an existing ConfigMap in your user {orch-namespace} to mount to all workspace containers.
 
 . Set the required labels for mounting.
 +
@@ -69,5 +70,5 @@ data:
   __<env_var_2>__: __<value_2>__
 ----
 
-When a {devworkspace} starts, environment variables `__<env_var_1>__` and `__<env_var_2>__` will be available in the {devworkspace} containers.
+When a workspace starts, environment variables `__<env_var_1>__` and `__<env_var_2>__` will be available in the workspace containers.
 ====

modules/end-user-guide/pages/mounting-persistent-volumes.adoc

@@ -7,18 +7,46 @@
 
 You can mount a Persistent Volume Claim (PVC) to your {devworkspace} containers. A PVC is used to request persistent storage resources which are abstracted from the user.
 
-To automatically mount an existing PVC to all {devworkspace} containers:
+{prod-short} provisions containerized development environments (workspaces). Without persistent volumes, every change would be lost when a running workspace is stopped.
+
+To avoid losing changes a user can either:
+
+* Pre-create a PVC with the right labels. This procedure is described in this section.
+* Specify a Persistent Volume (PV) in a Devfile that will be managed by {prod-short}. See link:https://devfile.io/docs/devfile/2.1.0/user-guide/specifying-persistent-storage[Specifiying persistent storage].
+
+Users will want to use Devfile-defined volumes when persisted data is mandatory for development and doesn't need to be shared across multiple workspaces.
+
+Alternatively, users should favor pre-created PVs when:
+
+* not all the developers of a project will need the PV, or
+* the PV lifecycle goes beyond the lifecycle of a single workspace, or
+* the data included in the PV is shared across workspaces.
+
+An example of a Devfile-defined PV is the `/projects/` folder of a workspace, which is by default.
+
+Pre-created PVs are mounted even if the workspace is run in ephemeral mode (the devfile uses the attribute controller.devfile.io/storage-type: ephemeral).
+
+[NOTE]
+====
+Persistent Volumes come at a cost. Attaching a persistent volume will make workspace startup slower.
+====
+
+[WARN]
+====
+There is a limitation when trying to run two concurrent workspaces if mounting a PV with the `ReadWriteOnce` access mode. The second workspace may fail to start.
+====
+
+To automatically mount an existing PVC to workspace containers:
 
 .Prerequisites
 
 * A running instance of {prod-short}.
 * You have GUI or CLI access to the {orch-name} cluster of your organization's {prod-short} instance.
+* You have created a new PVC or determined an existing one in your user {orch-namespace} to mount to all workspaces containers.
 * For CLI users: The `{orch-cli}` command-line tool is installed in the operating system you are using.
 
 .Procedure
 
-. Determine an existing PVC in your user {orch-namespace} to mount to all {devworkspace} containers.
-
 . Add label `controller.devfile.io/mount-to-devworkspace: true` to `__<PVC_name>__`.
 
 +

modules/end-user-guide/pages/mounting-secrets.adoc

@@ -5,19 +5,20 @@
 [id="mounting-secrets_{context}"]
 = Mounting Secrets
 
-You can automatically mount {orch-name} Secrets to all {devworkspace} containers, creating permanent mount points for components such as SSH key pairs or AWS authorization tokens.
+You can automatically mount {orch-name} Secrets to all workspace containers, creating permanent mount points for components such as SSH key pairs or AWS authorization tokens.
 
-Secrets are {orch-name} objects that store confidential data such as user names, passwords, authentication tokens, and configurations in an encrypted form.
+Secrets are {orch-name} objects that store confidential data such as usernames, passwords, authentication tokens, and configurations in an encrypted form.
 
 .Prerequisites
 
 * A running instance of {prod-short}.
 * You have GUI or CLI access to the {orch-name} cluster of your organization's {prod-short} instance.
+* You have created a new Secret or determined an existing one in your user {orch-namespace} to mount to all workspaces containers.
 * For CLI users: The `{orch-cli}` command line tool is installed in the operating system you are using.
 
 .Procedure
 
-. Determine an existing ConfigMap or Secret in your user {orch-namespace} to mount to all {devworkspace} containers.
+. Determine an existing ConfigMap or Secret in your user {orch-namespace} to mount to all workspace containers.
 
 . Set the required labels for mounting.
 +

modules/end-user-guide/pages/volumes-secrets-and-configmaps.adoc

@@ -1,12 +1,25 @@
-:navtitle: Volumes, ConfigMaps, and Secrets
+:navtitle: Injecting User Credentials and Configurations
 :keywords: user-guide, configuring, user, configmaps, secrets, volumes, mounting, mount
 :page-aliases: 
 
-[id="mounting-volumes-secrets-and-configmaps_{context}"]
-= Volumes, ConfigMaps, and Secrets
+[id="injecting-user-credentials-and-configurations_{context}"]
+= Injecting User Credentials and Configurations
 
-You can mount your xref:mounting-volumes.adoc[Persistent Volume Claims (PVC)], xref:mounting-configmaps.adoc[ConfigMaps], and xref:mounting-secrets.adoc[Secrets], such as a xref:git-credential-store.adoc[Git gredential store], into your {devworkspace} containers.
+== Mounting resources
+You can inject your user credentials, configurations, and persistent volumes into your workspace containers.
 
-The mounting process uses the standard {kubernetes} mounting mechanism. Resources are mounted when starting a new {devworkspace} or restarting an existing one.
+This can be done by mounting xref:mounting-persistent-volumes.adoc[Persistent Volume Claims (PVC)], xref:mounting-configmaps.adoc[ConfigMaps], and xref:mounting-secrets.adoc[Secrets] into your workspace containers.
 
-Mounting your existing resources to the {devworkspace} containers requires additional labels and annotations applied to your existing resources.
+Permanent mount points can be created for components such as:
+
+* Maven configuration, such as the `settings.xml` file 
+* SSH key pairs
+* AWS authorization tokens
+* Configuration files
+* Persistent storage
+* Git credentials store files
+
+The mounting process uses the standard {kubernetes} mounting mechanism, and requires additional labels and annotations applied to your existing resources. Resources are mounted when starting a new workspace or restarting an existing one.
+
+== Image pull Secrets
+You can configure image pull Secrets to be applied to workspace Pods to access container registries requiring authentication. See xref:image-pull-secrets.adoc[Creating image pull Secrets].