Update README.md to make contribution steps easier to follow

README.md

@@ -2,39 +2,93 @@
 
 ## About the Generator
 
-This repository introduces some utilities that can be used to extract the command tree from the CLI and Plug-ins, store the relevant command groups for third party conformant plugins in a legal-approved way (without exposing proprietary code), and generate a web help with those plug-ins included on demand.
+This repository introduces utilities that extract the command tree from the CLI and its installed plug-ins, store the relevant command groups for third party conformant plug-ins in a legal-approved way (without exposing proprietary code), and generate web help with those plug-ins included on demand.
+
+To contribute your plug-in's web help, follow the steps below for installing and using the project.
 
 ---
 
 ## Installing
 
-To install the necessary components, run `npm install`. For a minimal install, try `npm install --prod`.
+1. Clone this repository from GitHub:
+    ```bash
+    git clone https://github.com/zowe/zowe-cli-web-help-generator.git
+    cd zowe-cli-web-help-generator
+    ```
+
+2. Install project dependencies:
+    ```bash
+    npm install --prod
+    ```
+    > **Note:** If you plan to modify the scripts in this repo, omit the `--prod` flag to also install dev dependencies.
+
+3. Install the plug-in you want to contribute into Zowe CLI, if it is not already installed. If you do not have a globally installed Zowe CLI available, run:
+    ```bash
+    npx zowe plugins install <plugin name or path here>
+    ```
 
 ---
 
-## Using - Contributing to the Web Help
+## Contributing to the web help
+
+To add your conformant plug-in's commands, perform the following steps:
+> **Note:** All steps should be performed in the root of this project.
 
-To add your conformant plug-in's commands, please perform the following steps:
+1. Ensure the plug-in you want to contribute to the web help is installed in Zowe CLI.
 
-1. Ensure the plug-in that you would like to contribute to the Web Help is installed in Zowe CLI. You can use `npx zowe plugins install <plugin name or path here>` if you do not have a globally installed Zowe CLI available.
-2. Copy the template file `zowe.template.json` to `zowe.json` in the root of the project. This file is ignored by git. Customize this file to include the full names of command group(s) of your plugin(s), and the name(s) of your plugin's profile(s), like the following:
+    If it is not already installed, see Step 3 in the [Installing](#installing) section.
 
+2. Define command groups and profiles that your plug-in contributes.
+
+    - Copy the template file `zowe.template.json` to a new file named `zowe.json`. This file will be ignored by git.
+    - Customize this file to include the full names of command group(s) of your plug-in(s), and the name(s) of your plug-in's profile(s), like the following:
+        ```json
         {
-          "commandGroups": ["zos-files", "zos-jobs"],
-          "profiles": ["zosmf", "base"]
+          "commandGroups": ["zowe-cli-sample"],
+          "profiles": ["sample"]
         }
-    *Note: No @zowe scoped plug-ins should be included in this repository, and the above is merely for demonstration purposes.*
+        ```
+    > **Note:** No @zowe scoped plug-ins should be included in this repository, and the above is merely for demonstration purposes.
+
+3. (Optional) Include your copyright notice, which will show as a comment in the generated output.
+
+    Create a file named `.copyright` and add your copyright notice there. This file will be ignored by git. If no copyright is supplied, the following default copyright will be added:
+    ```
+    Copyright Contributors to the Zowe Project.
+    ```
 
-3. (Optional) Include your Copyright. Add your copyright text to a file named `.copyright` in the root of the repository. This file will be ignored by git. If no copyright is supplied, the following default copyright will be added:
+4. Use the web help generator to extract help from your plug-in's command definitions.
 
-        Copyright Contributors to the Zowe Project.
+    Run the following command:
+    ```bash
+    npm run contribute
+    ```
+    This will retrieve the CLI command tree from Zowe CLI and all installed plug-ins, and extract the above command group(s) and profile(s) to `.jsonc` files in the "commandGroups" and "profiles" directories.
 
-4. Run the `npm run contribute` command. This will retrieve the CLI command tree from Zowe CLI and all installed plug-ins, and extract the above command group(s) and profile(s) to the commandGroups and profiles directories.
-5. Commit the newly created files. Ensure the commit is signed off.
+5. Commit new files back to the GitHub repository.
+
+    - Commit the newly created `.jsonc` files to git. Ensure the commit is signed off (it must include a "Signed-off-by" line).
+        ```bash
+        git commit -s -m "Add <plugin name> plug-in"
+        ```
+    - Create a pull request in this repository that contributes the new files so that your plug-in will be included in web help for the next Zowe release.
 
 ---
 
-## Using - Generating the Web Help
+## Generating the web help
+
+To preview web help with your plug-in included locally, perform the following steps:
+
+1. Ensure the latest CLI and plug-ins are installed to generate up-to-date help.
+
+    Install the latest version of Zowe CLI, and all @zowe scoped plug-ins (CICS, DB2, FTP, IMS, and MQ for Zowe v2) if they are not already installed. If you do not have a globally installed Zowe CLI available, the CLI can also be accessed in this repository by running `npx zowe`.
+
+2. Build web help that includes all plug-ins contributed to this repository.
+
+    In the root of this project, run:
+    ```bash
+    npm run build
+    ```
+    This will generate the CLI command tree from the CLI and @zowe packages, merge all of the command groups in the defined folders, and generate the web help in the "generatedWebHelp" directory.
 
-1. Install the latest CLI, and all @zowe scoped plug-ins. The CLI can also be accessed in this repository with `npx zowe`. 
-2. Run the `npm run build` command. This will generate the CLI command tree from the CLI and @zowe packages, merge all of the command groups in the defined folders, and generate the web help in the generatedWebHelp directory.
+3. Open the file "generatedWebHelp/index.html" in your browser to view the generated web help.