Improve documentation for Code Review JCL: AKGCR

For customers using z/OS Source Code Analysis. They can use the Code Review (CR) features on both the client and host. The documentation is geared towards customers who are setting this up on the client side. For customers setting this up on the host side there is room for improvement. Especially in the scenario where a customer only tries to implement CR on the host side.

There is two sections for CR on the client and host:

The code review application - https://www.ibm.com/docs/en/developer-for-zos/15.0?topic=review-code-application

The code review application for z/OS - https://www.ibm.com/docs/en/developer-for-zos/15.0?topic=review-code-application-zos

If the customer directly starts with the CR on the host, they will find the sample job AKGCR. The sample JCL lists out the following DD's:

RULES    DD PATH='/var/akg/rules.dat'                        
CUSTRULE DD PATH='/var/akg/custom.rules.ccr'                
PROPERTY DD PATH='/var/akg/property.group.xml'              
EXTMAP   DD PATH='/var/akg/extension.mapping.zip'                          
BIMPORT  DD PATHOPTS=(ORDONLY),PATH='/var/akg/baseline.zip' 
 

There is no documentation within the CR z/OS section on setting up AKGCR. It does mention how to create the files but it is not really intuitive that the creation of the files occur on the client side, then need to be uploaded to the host, and then defined to AKGCR.

The section: 'Creating and uploading data files' - https://www.ibm.com/docs/en/developer-for-zos/15.0?topic=zos-creating-uploading-data-files, mentions "Some input parameters to the z/OS® source code application require a data file. Data files must be created on the local workstation and copied in binary format to a directory in z/OS UNIX System Services.". That helps but overall the documentation for the host side is a little vague. There is no direct reference to AKGCC or AKGCR to help customers get to the correct documentation.

It may also be helpful to add comments in the AKGCR and AKGCC sample jobs to instruct customers to refer to the 'The code review application for z/OS' section of our documentation for help on configuring and defining the data files.

For the data files it may also be useful to provide samples of the needed files that are packaged and included in the host install of z/OS Source Code Analysis.