Clarify usage of z/OS PT provisioned directories

And clarify zosptfile entries are for Node.js

Author: markcocker

docs/pages/cdp/cdp-Creating-Zowe-CLI-profiles.md

@@ -72,7 +72,7 @@ zowe zos-uss issue ssh 'uname -a'
 
 ### Create a cics-deploy profile
 
-The cics-deploy profile identifies the CICS environment for deployment. You need to know the following from your CICS system administrator:
+The cics-deploy profile identifies the CICS environment for deployment. An example of how to create an environment using using z/OS Provisioning Toolkit as described in [Provisioning a CICS region using z/OS PT](cdp-Provisioning-a-CICS-region-using-zospt). You need to know the following from your CICS system administrator:
 
 | Option | Description |
 | --- | --- |

docs/pages/cdp/cdp-Provisioning-a-CICS-region-using-zospt.md

@@ -9,21 +9,23 @@ folder: cdp
 toc: true
 ---
 
-The [z/OS Provisioning Toolkit](https://developer.ibm.com/mainframe/products/zospt/) (z/OS PT) provides a command line utility and z/OSMF workflows to provision CICS regions and other development environments on z/OS. This tutorial requires z/OS PT version 1.1.5 or above to be installed.
+The [z/OS Provisioning Toolkit](https://developer.ibm.com/mainframe/products/zospt/) (z/OS PT) provides a command line utility and z/OSMF workflows to provision CICS regions and other development environments on z/OS. This tutorial requires z/OS PT version 1.1.5 or above to be installed on z/OS.
 
 ### Prepare a z/OS PT image
 
-A z/OS PT image contains the configuration and files necessary to provision a CICS region. This is typically prepared by the CICS system administrator. The CICS image should include the following properties. Other properties are available to customise the CICS region to your requirements - see [Configuration properties for CICS images](https://www.ibm.com/support/knowledgecenter/en/SSXH44E_1.0.0/zospt/cics/zospt-cics-properties.html).
+A z/OS PT image contains the configuration and files necessary to provision a CICS region. This is typically prepared by the CICS system administrator. The main configuration is in the file `zosptfile` in the form of properties that are described in [Configuration properties for CICS images](https://www.ibm.com/support/knowledgecenter/en/SSXH44E_1.0.0/zospt/cics/zospt-cics-properties.html).
+
+For example, to support Node.js applications `zosptfile` should include:
 
 | zosptfile entry                      | Usage |
 | --- | -- |
-| `FROM cics_55` | Provision a CICS TS V5.5 region. Required to support Node.js applications. |
-| `ENV DFH_CICS_TYPE=MAS` | The CICS region should be managed by CPSM. |
-| `ENV DFH_CICSPLEX=` | The name of the CICSplex. |
-| `ENV DFH_NODE_HOME=` | The installation directory for IBM SDK for Node.js - z/OS. Required to support Node.js applications. |
-| `COPY bundles bundles` | Create an empty bundles directory in the provisioned file system to contain CICS bundles. |
+| `FROM cics_55` | Provision a CICS TS V5.5 region that is the minimum release that supports Node.js applications. |
+| `ENV DFH_CICS_TYPE=MAS` | CICS region should be managed by CPSM to enable the DFHDPLOY utility to deploy applications. |
+| `ENV DFH_CICSPLEX=` | Name of the CICSplex this region is to join. |
+| `ENV DFH_NODE_HOME=` | Installation directory for Node.js runtime provided by IBM SDK for Node.js - z/OS. |
+| `COPY bundles bundles` | Create an empty `bundles` directory in the provisioned file system to contain CICS bundles. |
 
-For example, to create the z/OS PT image source directory and configuration file, and build it ready for developers to provision CICS regions:
+To create a z/OS PT image source directory, a `zosptfile` file, and build it ready for developers to provision CICS regions, run the following commands on z/OS:
 
 ```console
 export ZOSPTIMAGE=~/zosptimages/cics_55_nodejs
@@ -43,16 +45,26 @@ chtag -tc UTF-8 $ZOSPTIMAGE/zosptfile
 zospt build $ZOSPTIMAGE -t cics_55_nodejs
 ```
 
-### Provision your CICS region and deploy a Node.js application
+### Provision your CICS region using a z/OS image
 
 1. Update your user `.profile` file on z/OS to run z/OS PT.
 
-   Add the directory to the `zospt` command to your PATH, and add the following environment variables as described in [Configuring z/OS Provisioning Toolkit](https://www.ibm.com/support/knowledgecenter/en/SSXH44E_1.0.0/zospt/zospt-configuring.html):
+   Add the directory to the `zospt` command to your PATH.
+   ```properties
+   export PATH=$PATH:zospt_directory/bin
+   ```
+
+   Optional: To avoid the password prompt for each zospt command, specify your password as the environment variable. Ensure others do not have access to read your .profile:
+
+   ```properties
+   export zospt_pw=
+   ```
+
+   Optional: If z/OSMF is configured with domain and tenant names that are not the default as described in [Configuring z/OS Provisioning Toolkit](https://www.ibm.com/support/knowledgecenter/en/SSXH44E_1.0.0/zospt/zospt-configuring.html), add the following environment variables:
 
    ```properties
    export zospt_domain=
    export zospt_tenant=
-   export zospt_pw=
    ```
 
 2. Provision your CICS region.
@@ -63,7 +75,7 @@ zospt build $ZOSPTIMAGE -t cics_55_nodejs
    zowe zos-uss issue ssh "zospt run cics_55_nodejs --name my_cics_region"
    ```
 
-3. Display the CICS region information.
+3. Display your CICS region information.
 
    ```console
    zowe zos-uss issue ssh "zospt inspect my_cics_region"
@@ -75,37 +87,50 @@ zospt build $ZOSPTIMAGE -t cics_55_nodejs
     "DFH_REGION_APPLID": "CICPY000",
     "DFH_REGION_ZFS_DIRECTORY": "/u/cicprov/mnt/CICPY000",</pre>
 
-4. Update your Zowe CLI cics-deploy profile options.
+    Your applications can make use of the directories and files under the DFH_REGION_ZFS_DIRECTORY path:
+
+   | DFH_REGION_ZFS_DIRECTORY<br>sub-directory | Usage |
+   | --- | -- |
+   | /JVMProfiles | JVM server profiles |
+   | /bundles | CICS bundles |
+   | /dfhconfig | CICS configuration files |
+   | /dfhconfig/nodejsprofiles/general.profile | General profile containing values for WORK_DIR and NODE_HOME. Node.js application should include this by adding `%INCLUDE=&USSCONFIG;/nodejsprofiles/general.profile` to their CICS Node.js application profile |
+   | /workdir | Trace, log and configuration files create by applications, Node.js runtimes, Java runtimes, and CICS runtimes |
+
 
-   Update `--scope` to be the value from DFH_REGION_APPLID, and `--bundle-directory` to be a bundles subdirectory of DFH_REGION_ZFS_DIRECTORY. For example:
+4. Update your Zowe CLI cics-deploy profile options to deploy to your CICS region by default.
+
+   Update `--scope` to be the value from DFH_REGION_APPLID, and `--bundle-directory` to be the `bundles` subdirectory of DFH_REGION_ZFS_DIRECTORY. For example:
 
    ```console
-   zowe profiles update cics-deploy cics --scope CICPY000 --bundle-directory /u/cicprov/mnt/CICPY000/bundles
+   zowe profiles update cics-deploy cics --scope CICPY000 --bundle-directory "/u/cicprov/mnt/CICPY000/bundles"
    ```
 
-You are now ready to deploy applications to the provisioned CICS region. You can try this out by following the steps in [Deploying your first Node.js app](cdp-Deploying-your-first-nodejs-app).
+### Deploying an application to your CICS region
+
+You are now ready to deploy applications to the provisioned CICS region. You can try this out by following the steps in [Deploying your first Node.js app](cdp-Deploying-your-first-nodejs-app). During deployment, the CICS bundle will be copied into the `/bundles` directory, and output files will be written into a sub-directory of `/workdir`.
 
 ### Stop your CICS region
 
-The CICS region and the applications running in it can be stopped if you are not going to be using them for a while by using command:
+The CICS region and the applications running in it can be stopped if you are not going to be using them for a while by using the following command:
 
 ```console
 zowe zos-uss issue ssh "zospt stop my_cics_region"
 ```
 
 ### Start your CICS region
 
-The CICS region can be started after it was previously stopped, or the z/OS system was restarted, by using command:
+The CICS region can be started after it was previously stopped, or the z/OS system was restarted, by using the following command:
 
 ```console
 zowe zos-uss issue ssh "zospt start my_cics_region"
 ```
 
 ### Deprovision your CICS region
 
-The CICS region can be stopped and removed using the following commands. This will remove the z/OS directory used to upload your CICS bundles:
+The CICS region can be stopped and removed completely using the following commands. This will remove the z/OS directory used to upload your CICS applications:
 
 ```console
 zowe zos-uss issue ssh "zospt stop my_cics_region"
 zowe zos-uss issue ssh "zospt rm my_cics_region"
-```
+```