docs: improve readme style

Author: vburckhardt

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "go.sum|^.secrets.baseline$",
     "lines": null
   },
-  "generated_at": "2024-05-03T08:36:56Z",
+  "generated_at": "2024-05-07T11:31:16Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -82,23 +82,23 @@
         "hashed_secret": "bbc4e9d52252171a3a306be55086c65b126189e8",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 35,
+        "line_number": 37,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "d9e9019d9eb455a3d72a3bc252c26927bb148a10",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 52,
+        "line_number": 54,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "b13d7622394e85c3b2694f426bc096b093764462",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 56,
+        "line_number": 58,
         "type": "Secret Keyword",
         "verified_result": null
       }

README.md

@@ -1,41 +1,44 @@
-# Retrieval Augmented Generation (RAG) stack
+# Retrieval Augmented Generation Pattern for Watsonx on IBM Cloud
 
-To run the full stack, follow these steps. These steps will be updated as development progresses on the stack and underlying DAs.
+The following [deployable architecture](https://cloud.ibm.com/docs/secure-enterprise?topic=secure-enterprise-understand-module-da#what-is-da) automates the deployment of a sample GenAI Pattern on IBM Cloud, including all underlying infrastructure. This architecture implements the best practices for Watsonx GenAI Pattern deployment on IBM Cloud, as described in the [reference architecture](https://cloud.ibm.com/docs/pattern-genai-rag?topic=pattern-genai-rag-genai-pattern).
 
-## 1. Deploy the stack in a new project from catalog
+# Deployment Details
 
-Catalog url: https://cloud.ibm.com/catalog/7df1e4ca-d54c-4fd0-82ce-3d13247308cd/architecture/Retrieval_Augmented_Generation_Pattern-5fdd0045-30fc-4013-a8bc-6db9d5447a52?bss_account=9f9af00a96104f49b6509aa715f9d6a5
+To run the full stack, follow these steps. These steps will be updated as development progresses on the stack and underlying deployable architectures.
 
-Click the "Add to project" button, and select create in new project.
+## 1. Deploy the Stack in a New Project from Catalog
 
-## 2. Prereqs in target account
+Catalog URL: https://cloud.ibm.com/catalog/7df1e4ca-d54c-4fd0-82ce-3d13247308cd/architecture/Retrieval_Augmented_Generation_Pattern-5fdd0045-30fc-4013-a8bc-6db9d5447a52?bss_account=9f9af00a96104f49b6509aa715f9d6a5
+
+Click the "Add to Project" button and select "Create in new project."
+
+## 2. Prerequisites in Target Account
 
 Before deploying the stack, ensure you have:
-- Created an API key in the target account with sufficient permissions. Note the API key, as it will be used later.
-- For now, grant it admin privileges. The exact permissions required will be refined in future versions.
-- Install the IBM Cloud CLI's Project addon using `ibmcloud plugin install project` command. More info here: https://cloud.ibm.com/docs/cli?topic=cli-projects-cli
 
+* Created an API key in the target account with sufficient permissions. Note the API key, as it will be used later. For now, grant it admin privileges. The exact permissions required will be refined in future versions.
+* Installed the IBM Cloud CLI's Project add-on using the `ibmcloud plugin install project` command. More information is available here: https://cloud.ibm.com/docs/cli?topic=cli-projects-cli
 
-## 3. Set the input configuration for the stack
+## 3. Set the Input Configuration for the Stack
 
-- Clone this repository locally.
-- Create a file with name ".def.json" with the following content.
+* Clone this repository locally.
+* Create a file named ".def.json" with the following content:
 
 **Important**:
-- Ensure region is either us-south or eu-de as watsonx can only be deployed in those 2 locations for now.
-- Ensure that the prefix is globally unique. It is used for the container registry namespace (which needs to be globally unique) in this alpha version.
-- If specifying `existing_secrets_manager_crn`, the ibmcloud_api_key that is passed as an input must have the documented read and write access to the instance
-- If specifying `existing_secrets_manager_crn`, ensure that the default security group does not contain secrets named `signing-key` and `ibmcloud-api-key` . The RAG DA currently always attempt to create secret with those names (temporary issue - to be fixed).
+* Ensure the region is either us-south or eu-de, as Watsonx can only be deployed in those two locations for now.
+* Ensure that the prefix is globally unique. It is used for the container registry namespace (which needs to be globally unique) in this alpha version.
+* If specifying `existing_secrets_manager_crn`, the `ibmcloud_api_key` that is passed as an input must have the documented read and write access to the instance.
+* If specifying `existing_secrets_manager_crn`, ensure that the default security group does not contain secrets named `signing-key` and `ibmcloud-api-key`. The RAG DA currently always attempts to create a secret with those names (temporary issue - to be fixed).
 
 ```json
 {
     "inputs": {
         "prefix": "<prefix for resources name - ensure unique>",
         "ibmcloud_api_key": "<API Key of the target account with sufficient permissions>",
-        "resource_group_name": "<target resource group - name of a new resource group that the stack will creates>",
+        "resource_group_name": "<target resource group - name of a new resource group that the stack will create>",
         "region": "<region where all resources are deployed>",
         "sample_app_git_url": "https://github.com/IBM/gen-ai-rag-watsonx-sample-application",
-        "watsonx_admin_api_key": "<optional - admin key to use for watson if different from ibmcloud_api_key>",
+        "watsonx_admin_api_key": "<optional - admin key to use for Watsonx if different from ibmcloud_api_key>",
         "signing_key": "signing key used to sign build artifacts",
         "existing_secrets_manager_crn": "<optional> - reuse an existing secret manager instance",
         "enable_platform_logs_metrics": "<optional> - set to true to enable observability instance to capture regional logs"
@@ -52,7 +55,7 @@ Example:
         "resource_group_name": "stack-service-rg",
         "region": "eu-de",
         "sample_app_git_url": "https://github.com/IBM/gen-ai-rag-watsonx-sample-application",
-        "watsonx_admin_api_key": "<optional - admin key to use for watson if different from ibmcloud_api_key>",
+        "watsonx_admin_api_key": "<optional - admin key to use for Watsonx if different from ibmcloud_api_key>",
         "signing_key": "signing key used to sign build artifacts",
         "enable_platform_logs_metrics": "false",
         "existing_secrets_manager_crn": "crn:v1:bluemix:public:secrets-manager:us-south:a/190c293e9fda4c6684b5acf4b17871b8:14580411-4fa2-42d3-af3f-ab7fc6371b6d::"
@@ -63,20 +66,20 @@ Example:
 
 ## 4. Run ./deploy-many.sh
 
-- Ensure you are login into the account containing the Cloud project with the stack using ibmcloud login --sso
-- Execute ./deploy-many.sh with project name, stack name and optional configuration name pattern. The selected non-stack configruations will be processed by their name in alphabetical order. Using configuration name pattern (regex can be used - make sure to enclose it in quotes) you can chose which configurations are deployed
+* Ensure you are logged in to the account containing the Cloud project with the stack using `ibmcloud login --sso`.
+* Execute `./deploy-many.sh` with the project name, stack name, and optional configuration name pattern. The selected non-stack configurations will be processed by their name in alphabetical order. Using the configuration name pattern (regex can be used - make sure to enclose it in quotes), you can choose which configurations are deployed.
 
-Example 1 - update stack inputs for stack configuration `RAG` and process all non-stack configurations in the project:
+Example 1 - Update stack inputs for stack configuration `RAG` and process all non-stack configurations in the project:
 ```bash
 ./deploy-many.sh my-test-project RAG
 ```
 
-Example 2 - update stack inputs and process some configurations in the project:
+Example 2 - Update stack inputs and process some configurations in the project:
 ```bash
 ./deploy-many.sh my-test-project RAG 'RAG-1|RAG-4|RAG-5'
 ```
 
-Example 3 - simulate updating stack inputs and validating some configurations in the project in dry-run mode (no changes or actual validation or deployments is done):
+Example 3 - Simulate updating stack inputs and validating some configurations in the project in dry-run mode (no changes or actual validation or deployments are done):
 ```bash
 DRY_RUN=true ./deploy-many.sh my-test-project RAG 'RAG-1|RAG-4|RAG-5'
 ```

ibm_catalog.json

@@ -14,7 +14,7 @@
 				"watson",
 				"ai"
 			],
-			"short_description": "An automated solution that deploys a sample application illustrating how to implement the RAG Pattern with watsonx.ai and IBM Cloud services.",
+			"short_description": "An automated solution that deploys a sample application illustrating how to implement the RAG Pattern with watson.ai and IBM Cloud services.",
 			"offering_icon_url": "https://globalcatalog.cloud.ibm.com/api/v1/1082e7d2-5e2f-0a11-a3bc-f88a8e1931fc/artifacts/solution.svg",
 			"flavors": [
 				{
@@ -104,7 +104,7 @@
 					"architecture": {
 						"features": [
 							{
-								"title": "Deploy a banking retrieval augmented generation app to Code Engine using Continous Delivery.",
+								"title": "Deploy a banking retrieval augmented generation (RAG) app to IBM Cloud Code Engine using Continous Delivery.",
 								"description": ""
 							}
 						],