Merge pull request #55 from vera-chan/doc-issues

stewartfrancis · web-flow · commit fc6179e59e3a · 2021-02-03T09:54:31.000Z
address doc issues from review
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,10 +1,4 @@
-# How to contribute
-
-Thank you for contributing to this project.
-
-We welcome bug reports and discussions about new function in the issue tracker, and we also welcome proposed new features or bug fixes via pull requests.
-
-You should read these guidelines to help you contribute.
+# Developer guide
 
 ## Reporting a bug
 
diff --git a/README.md b/README.md
@@ -4,9 +4,7 @@ IBM z/OS CICS collection
 The **IBM® z/OS® CICS® collection**, also represented as **ibm\_zos\_cics**
 in this document, is part of the broader initiative to bring Ansible® Automation to IBM Z® through the offering **Red Hat® Ansible Certified Content for IBM Z**. The IBM z/OS CICS collection supports management of CICS resources and definitions via the CMCI REST API provided by CICS.
 
-This CICS collection can work independently from other IBM z/OS modules on Ansible to perform tasks in CICS. You can, however, use it in conjunction with other IBM z/OS collections such as the 
-[IBM z/OS core collection](https://github.com/ansible-collections/ibm_zos_core) 
-to deliver a solution that will enable you to automate tasks on z/OS.
+This CICS collection can work in conjunction with or independently from other IBM z/OS collections on Ansible such as the [IBM z/OS core collection](https://github.com/ansible-collections/ibm_zos_core). When used alone, it performs automation tasks solely in CICS. When using it together with other z/OS collections, you can achieve a more powerful solution for automating tasks on z/OS.
 
 
 Red Hat Ansible Certified Content for IBM Z
@@ -23,18 +21,9 @@ Features
 
 The IBM CICS collection includes
 [modules](https://github.com/ansible-collections/ibm_zos_cics/tree/master/plugins/modules/),
-[sample playbooks](https://github.com/ansible-collections/ibm_zos_cics/tree/master/playbooks/),
+[sample playbooks](https://github.com/IBM/z_ansible_collections_samples),
 and ansible-doc to automate tasks in CICS.
 
-Contributing
-============
-
-Thank you for contributing to this project.
-
-We welcome bug reports and discussions about new function in the issue tracker, and we also welcome proposed new features or bug fixes via pull requests.
-
-For contribution guidelines, see [How to contribute](https://github.com/ansible-collections/ibm_zos_cics/tree/master/CONTRIBUTING.md).
-
 
 Copyright
 =========
diff --git a/docs/ansible_content.rst b/docs/ansible_content.rst
@@ -2,13 +2,13 @@
 .. © Copyright IBM Corporation 2020                                          .
 .. ...........................................................................
 
-IBM z/OS CICS Collection
+CICS Collection
 ========================
 
 The **IBM® z/OS® CICS® collection**, also represented as **ibm\_zos\_cics**
-in this document, provides tasks to define, install, and perform actions on CICS definitions and resources such as creating a PROGRAM definition, installing and updating it, and deleting the definition.
+in this document, is part of the broader initiative to bring Ansible® Automation to IBM Z® through the offering Red Hat® Ansible Certified Content for IBM Z®. It provides tasks to define, install, and perform actions on CICS definitions and resources such as creating a PROGRAM definition, installing and updating it, and deleting the definition.
 
-The **IBM z/OS CICS collection** can work independently from other IBM z/OS modules on Ansible® to perform tasks in CICS. You can, however, to use it in conjunction with the `IBM z/OS core collection`_ to deliver a solution that will enable you to automate tasks on z/OS. If you choose to do that, you can refer to their documentation for the extra configuration needed.
+The CICS collection can work in conjunction with or independently from other IBM z/OS collections on Ansible such as the `IBM z/OS core collection`_. When used alone, it performs automation tasks solely in CICS. When using it together with other z/OS collections, you can achieve a more powerful solution for automating tasks on z/OS.
 
 
 .. _IBM z/OS core collection:
diff --git a/docs/source/community_guides.rst b/docs/source/community_guides.rst
@@ -6,13 +6,19 @@
 Contributing
 ============
 
-Thank you for contributing to this project.
+We are not currently accepting community contributions. However, we encourage you to open `git issues`_ for bugs, comments or feature requests.
 
-We welcome bug reports and discussions about new function in the issue tracker, and we also welcome proposed new features or bug fixes via pull requests.
+Review this content periodically to learn when and how to make contributions in the future. For the latest information on open issues, see: `git issues`_.
 
-For contribution guidelines, see `How to contribute`_.
 
-.. _How to contribute:
+Development
+===========
+
+For a developer guide on how to develop and run test cases for IBM® z/OS® CICS® collection, see `Developer guide`_.
+
+.. _git issues:
+   https://github.com/ansible-collections/ibm_zos_cics/issues
+.. _Developer guide:
    https://github.com/ansible-collections/ibm_zos_cics/tree/master/CONTRIBUTING.md
 
 
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -9,28 +9,6 @@ Always check that your control node has fulfilled the :doc:`requirements` before
 
 Then, follow the guidance to install the collection from Ansible® Galaxy or a custom Galaxy server. More ways to install an Ansible collection are documented at `installing collections`_.
 
-.. note:: Python module dependencies are not installed with the collection. To use the collection, you must install Python dependencies where the task will be running, in our case, the control node. See `Installing Python dependencies`_.
-
-Installing Python dependencies
--------------------------------
-You can use the supplied ``prod-requirements`` file to install the dependencies:
-
-.. code-block:: sh
-
-   pip install prod-requirements.txt
-
-
-Alternatively, you can install the dependencies manually:
-
-* `requests`_ package
-* `xmltodict`_ 0.12.0
-
-.. _requests:
-   https://pypi.org/project/requests/
-
-.. _xmltodict:
-   https://pypi.org/project/xmltodict/
-
 
 Installing from Ansible Galaxy
 ------------------------------
diff --git a/docs/source/modules/cmci_action.rst b/docs/source/modules/cmci_action.rst
@@ -150,7 +150,7 @@ cmci_user
 
      
 context
-  If CMCI is installed in a CICSPlex® SM environment, *context* is the name of the CICSplex or CMAS associated with the request, for example, ``PLEX1``. to determine whether a CMAS can be specified as *context*, see the **CMAS context** entry in the CICSPlex SM resource table reference of a resource. For example, according to the `PROGRAM resource table <https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.6.0/reference-cpsm-restables/cpsm-restables/PROGRAMtab.html>`_, CMAS context is not supported for PROGRAM.
+  If CMCI is installed in a CICSPlex® SM environment, *context* is the name of the CICSplex or CMAS associated with the request, for example, ``PLEX1``. To determine whether a CMAS can be specified as *context*, see the **CMAS context** entry in the CICSPlex SM resource table reference of a resource. For example, according to the `PROGRAM resource table <https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.6.0/reference-cpsm-restables/cpsm-restables/PROGRAMtab.html>`_, CMAS context is not supported for PROGRAM.
 
   If CMCI is installed in a single region (SMSS), *context* is the APPLID of the CICS region associate with the request.
 
diff --git a/docs/source/modules/cmci_create.rst b/docs/source/modules/cmci_create.rst
@@ -8,8 +8,8 @@
 .. _cmci_create_module:
 
 
-cmci_create -- Create CICS and CICSPlex SM definitions in CSD and BAS repositories
-==================================================================================
+cmci_create -- Create CICS and CICSPlex SM definitions
+======================================================
 
 
 
@@ -20,7 +20,7 @@ cmci_create -- Create CICS and CICSPlex SM definitions in CSD and BAS repositori
 
 Synopsis
 --------
-- Create definitional CICS® or CICSPlex® SM resources in CICS regions, by initiating POST requests via the CMCI REST API. The CMCI REST API can be configured in CICSPlex SM or stand-alone regions (SMSS). For information about the API, see `CMCI REST API <https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/reference-system-programming/cmci/clientapi_overview.html>`_. For information about how to compose POST requests, see `CMCI POST requests <https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/reference-system-programming/cmci/clientapi_post.html>`_.
+- Create definitional CICS® or CICSPlex® SM resources in CSD and BAS repositories, by initiating POST requests via the CMCI REST API. The CMCI REST API can be configured in CICSPlex SM or stand-alone regions (SMSS). For information about the API, see `CMCI REST API <https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/reference-system-programming/cmci/clientapi_overview.html>`_. For information about how to compose POST requests, see `CMCI POST requests <https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/reference-system-programming/cmci/clientapi_post.html>`_.
 
 
 
@@ -119,7 +119,7 @@ cmci_user
 
      
 context
-  If CMCI is installed in a CICSPlex® SM environment, *context* is the name of the CICSplex or CMAS associated with the request, for example, ``PLEX1``. to determine whether a CMAS can be specified as *context*, see the **CMAS context** entry in the CICSPlex SM resource table reference of a resource. For example, according to the `PROGRAM resource table <https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.6.0/reference-cpsm-restables/cpsm-restables/PROGRAMtab.html>`_, CMAS context is not supported for PROGRAM.
+  If CMCI is installed in a CICSPlex® SM environment, *context* is the name of the CICSplex or CMAS associated with the request, for example, ``PLEX1``. To determine whether a CMAS can be specified as *context*, see the **CMAS context** entry in the CICSPlex SM resource table reference of a resource. For example, according to the `PROGRAM resource table <https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.6.0/reference-cpsm-restables/cpsm-restables/PROGRAMtab.html>`_, CMAS context is not supported for PROGRAM.
 
   If CMCI is installed in a single region (SMSS), *context* is the APPLID of the CICS region associate with the request.
 
diff --git a/docs/source/modules/cmci_delete.rst b/docs/source/modules/cmci_delete.rst
@@ -110,7 +110,7 @@ cmci_user
 
      
 context
-  If CMCI is installed in a CICSPlex® SM environment, *context* is the name of the CICSplex or CMAS associated with the request, for example, ``PLEX1``. to determine whether a CMAS can be specified as *context*, see the **CMAS context** entry in the CICSPlex SM resource table reference of a resource. For example, according to the `PROGRAM resource table <https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.6.0/reference-cpsm-restables/cpsm-restables/PROGRAMtab.html>`_, CMAS context is not supported for PROGRAM.
+  If CMCI is installed in a CICSPlex® SM environment, *context* is the name of the CICSplex or CMAS associated with the request, for example, ``PLEX1``. To determine whether a CMAS can be specified as *context*, see the **CMAS context** entry in the CICSPlex SM resource table reference of a resource. For example, according to the `PROGRAM resource table <https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.6.0/reference-cpsm-restables/cpsm-restables/PROGRAMtab.html>`_, CMAS context is not supported for PROGRAM.
 
   If CMCI is installed in a single region (SMSS), *context* is the APPLID of the CICS region associate with the request.
 
diff --git a/docs/source/modules/cmci_get.rst b/docs/source/modules/cmci_get.rst
@@ -110,7 +110,7 @@ cmci_user
 
      
 context
-  If CMCI is installed in a CICSPlex® SM environment, *context* is the name of the CICSplex or CMAS associated with the request, for example, ``PLEX1``. to determine whether a CMAS can be specified as *context*, see the **CMAS context** entry in the CICSPlex SM resource table reference of a resource. For example, according to the `PROGRAM resource table <https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.6.0/reference-cpsm-restables/cpsm-restables/PROGRAMtab.html>`_, CMAS context is not supported for PROGRAM.
+  If CMCI is installed in a CICSPlex® SM environment, *context* is the name of the CICSplex or CMAS associated with the request, for example, ``PLEX1``. To determine whether a CMAS can be specified as *context*, see the **CMAS context** entry in the CICSPlex SM resource table reference of a resource. For example, according to the `PROGRAM resource table <https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.6.0/reference-cpsm-restables/cpsm-restables/PROGRAMtab.html>`_, CMAS context is not supported for PROGRAM.
 
   If CMCI is installed in a single region (SMSS), *context* is the APPLID of the CICS region associate with the request.
 
diff --git a/docs/source/modules/cmci_update.rst b/docs/source/modules/cmci_update.rst
@@ -119,7 +119,7 @@ cmci_user
 
      
 context
-  If CMCI is installed in a CICSPlex® SM environment, *context* is the name of the CICSplex or CMAS associated with the request, for example, ``PLEX1``. to determine whether a CMAS can be specified as *context*, see the **CMAS context** entry in the CICSPlex SM resource table reference of a resource. For example, according to the `PROGRAM resource table <https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.6.0/reference-cpsm-restables/cpsm-restables/PROGRAMtab.html>`_, CMAS context is not supported for PROGRAM.
+  If CMCI is installed in a CICSPlex® SM environment, *context* is the name of the CICSplex or CMAS associated with the request, for example, ``PLEX1``. To determine whether a CMAS can be specified as *context*, see the **CMAS context** entry in the CICSPlex SM resource table reference of a resource. For example, according to the `PROGRAM resource table <https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.6.0/reference-cpsm-restables/cpsm-restables/PROGRAMtab.html>`_, CMAS context is not supported for PROGRAM.
 
   If CMCI is installed in a single region (SMSS), *context* is the APPLID of the CICS region associate with the request.
 
diff --git a/docs/source/requirements.rst b/docs/source/requirements.rst
@@ -11,8 +11,7 @@ The nodes listed below require these specific versions of software:
 Control node
 ------------
 
-A control node is any machine with Ansible® installed. From the control node,
-you can run commands and playbooks from a laptop, desktop, or server. The following software must be installed on the control node.
+A control node is any machine with Ansible® installed. You can run commands and playbooks from a control noede, be it a laptop, desktop, or server. The following software must be installed on the control node.
 
 .. note:: The IBM® z/OS® CICS® collection cannot run on a Windows system.
 
@@ -33,7 +32,7 @@ you can run commands and playbooks from a laptop, desktop, or server. The follow
 Managed node
 ------------
 
-The CMCI tasks in the IBM z/OS CICS collection interact with the managed node over an HTTP connection by leveraging the `CMCI REST API`_. Therefore, you don't need to run the CMCI tasks on the managed node. You need, in this case, to delegate Ansible tasks to run on the local control node, for example, by specifying ``delegate_to: 'localhost'`` for the tasks in the playbook. For detailed requirements, see :doc:`requirements_managed`.
+The CMCI tasks in the IBM z/OS CICS collection interact with the managed node over an HTTP connection by leveraging the `CMCI REST API`_. Therefore, an SSH connection is not necessary. Instead, you can delegate the CMCI tasks to run on the control node directly, for example, by specifying ``delegate_to: 'localhost'`` for the tasks in the playbook. For detailed requirements, see :doc:`requirements_managed`.
 
 
 .. toctree::
diff --git a/docs/source/requirements_managed.rst b/docs/source/requirements_managed.rst
@@ -5,16 +5,37 @@
 Requirements of managed nodes
 =============================
 
-The managed node is the host that is managed by Ansible®, as identified in the Ansible inventory.
+The CMCI tasks in the **IBM® z/OS® CICS® collection** interact with the managed node over an HTTP connection by leveraging the `CMCI REST API`_. Therefore, an SSH connection is not necessary. Instead, you can delegate Ansible tasks to run on the control node, for example, by specifying ``delegate_to: 'localhost'`` for the task in the playbook. For more ways of delegating tasks, see `Controlling where tasks run`_.
 
-The CMCI tasks in the **IBM® z/OS® CICS® collection** interact with the managed node over an HTTP connection by leveraging the `CMCI REST API`_. Therefore, you don't need to run the CMCI tasks on the managed node. You need, in this case, to delegate Ansible tasks to run on the local control node, for example, by specifying ``delegate_to: 'localhost'`` for the task in the playbook. For more ways of delegating tasks, see `Controlling where tasks run`_.
+Delegating tasks to run on the control node saves you the complexity of configuring an unnecessary SSH connection and installing module dependencies on the remote host.
 
-The managed node must follow these requirements to use the CICS collection:
+The requirements of the managed node are as follows:
 
 * IBM CICS V4.2 or later
 * A `CMCI connection`_ must be set up in either a CICSplex or a stand-alone CICS region
+* Python module dependencies:
 
-If you want to use the CICS collection in conjunction with other IBM z/OS collections, you might need to run some tasks on the managed node. In that case, your managed node must also follow the requirements of those collections, for example, `IBM z/OS core managed node requirements`_.
+  * `requests`_
+  * `xmltodict`_
+
+  If you delegate the tasks to run on your localhost, the Python module dependencies need to be installed on your localhost instead. You can install them from CLI:
+
+  .. code-block:: sh
+
+     pip install requests xmltodict
+
+  You can also install them using the playbook. See this sample (link to be added) for an example.
+
+.. _requests:
+   https://pypi.org/project/requests/
+
+.. _xmltodict:
+   https://pypi.org/project/xmltodict/
+
+
+If you use the CICS collection in conjunction with other IBM z/OS collections, you won't be able to delegate all tasks to your localhost. In that case, your managed node must also follow the requirements of those collections, for example, `IBM z/OS core managed node requirements`_.
+
+If you use the CICS collection alone but don't delegate the CICS tasks to your localhost, your managed node must also follow the `IBM z/OS core managed node requirements`_ except that IBM Z Open Automation Utilities (ZOAU) is not required.
 
 .. _z/OS OpenSSH:
    https://www.ibm.com/support/knowledgecenter/SSLTBW_2.2.0/com.ibm.zos.v2r2.e0za100/ch1openssh.htm
diff --git a/plugins/doc_fragments/cmci.py b/plugins/doc_fragments/cmci.py
@@ -65,7 +65,7 @@ class ModuleDocFragment(object):
     description:
       - If CMCI is installed in a CICSPlex® SM environment, I(context) is the
         name of the CICSplex or CMAS associated with the request, for example,
-        C(PLEX1). to determine whether a CMAS can be specified as I(context),
+        C(PLEX1). To determine whether a CMAS can be specified as I(context),
         see the B(CMAS context) entry in the CICSPlex SM resource table reference of a resource.
         For example, according to the L(PROGRAM resource table,
         https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.6.0/reference-cpsm-restables/cpsm-restables/PROGRAMtab.html),
diff --git a/plugins/modules/cmci_create.py b/plugins/modules/cmci_create.py
@@ -10,11 +10,11 @@
 DOCUMENTATION = r'''
 ---
 module: cmci_create
-short_description: Create CICS and CICSPlex SM definitions in CSD and BAS repositories
+short_description: Create CICS and CICSPlex SM definitions
 description:
-  - Create definitional CICS® or CICSPlex® SM resources in CICS
-    regions, by initiating POST requests via the CMCI REST API. The CMCI REST API can be configured in CICSPlex SM
-    or stand-alone regions (SMSS). For information about the API, see
+  - Create definitional CICS® or CICSPlex® SM resources in CSD and BAS repositories, 
+    by initiating POST requests via the CMCI REST API. The CMCI REST API can be configured
+    in CICSPlex SM or stand-alone regions (SMSS). For information about the API, see
     L(CMCI REST API,
     https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/reference-system-programming/cmci/clientapi_overview.html).
     For information about how to compose POST requests, see L(CMCI POST requests,
