Merge pull request #272 from validatedpatterns/contribute-review-1

Contribute review 1

Author: mbaldessari

content/contribute/creating-a-pattern.md

@@ -11,9 +11,9 @@ The validated patterns community has relied on existing architectures that have
 
 The validated patterns framework is much more of a best practice of structuring the various configuration assets and integrating with GitOps and DevOps tools.
 
-Therefore the question really is: how do I move my successful architecture solution into a sustainable GitOps/DevOps framework? And that is what we are going to do in this section.
+Therefore the question really is: how do I move my successful architecture solution into a sustainable GitOps/DevOps framework? And that is what we are going to address this section.
 
-So how do you take a current application workload and move it to the Validated Pattern framework? One of the first things that you should do is look at your current implementation of your workload and identify the kubernetes manifests that are involved in order to run the workloads.
+So how do you take a current application workload and move it to the Validated Pattern framework? One of the first things that you should do is look at the current implementation of your workload and identify the kubernetes manifests that are involved in order to run the workloads.
 
 ## Prerequisites
 
@@ -28,7 +28,7 @@ The validated patterns framework is much more of a best practice of structuring
 Therefore the question really is: How do I move my successful architecture solution into a sustainable GitOps/DevOps framework? And that is what we are going to do in this section.
 
 ## Requirements for creating a new pattern
-* The patterns framework requires some artifacts like OpenShift GitOps (ArgoCD) in order to provide the GitOps automation. All existing patterns use OpenShift GitOps as a starting point. The [multicloud-gitops pattern](/patterns/multicloud-gitops) is the most fundamental of patterns and therefore it is recommended to use it as a base pattern. I.e Create a new pattern based on it.
+* The patterns framework requires some artifacts like OpenShift GitOps (ArgoCD) in order to provide the GitOps automation. All existing patterns use OpenShift GitOps as a starting point. The [multicloud-gitops pattern](/patterns/multicloud-gitops) is the most fundamental of patterns and therefore it is recommended to use it as a base pattern; i.e create a new pattern based on it.
 * Create a new branch on your new pattern to perform the initial changes.
 * Deploy the initial new pattern pattern to the cluster.
 
@@ -41,9 +41,9 @@ One of the first things that you should do is look at your current implementatio
 There are 4 values files that make up any Validated Pattern.  The values files are:
 
 * values-<main-hub>.yaml  (e.g. values-datacenter.yaml)
-* values-<edge>.yaml (e.g. values-edge-site.yaml or values-factory.yaml)
-* values-global.yaml
-* values-secrets.yaml
+* values-<edge>.yaml (e.g. values-edge-site.yaml, values-factory.yaml, values-development.yaml, etc.)
+* values-global.yaml (used to override global values across clusters)
+* values-secrets.yaml (NEVER commit this to github, gitlab etc. This file should be in a safe directory on your laptop)
 
 ## Operators into framework
 
@@ -128,7 +128,7 @@ applications:
       name: helm-with-kustomize
 ```
 
-In the above example `acm` (ACM) is part of the main `datacenter` deployment, as is `cool-app`. However, `central-kafka` is part of `backend-storage`.
+In the above example `acm` (ACM) is part of the main `datacenter` deployment, as is `cool-app`. However, `central-kafka` is part of `backend-storage`. All these deployment are on the same datacenter cluster.
 
 The `path:` tag tells OpenShift GitOps where to find the Helm charts needed to deploy this application (refer back to the [charts directory description](https://validatedpatterns.io/building-vps/structure/#the-charts-directory) for more details). OpenShift GitOps will continuously monitor for changes to artifacts in that location for updates to apply.
 

content/contribute/extending-a-pattern.md

@@ -8,23 +8,25 @@ aliases: /extending-a-pattern/
 # Extending an existing pattern
 
 ## Introduction to extending a pattern using a fork
-Extending an existing pattern usually means adding a new product and/or configuration to the existing pattern. This usually requires four steps:
+Extending an existing pattern refers to adding a new product and/or configuration to an existing pattern. For example a pattern might be a great fit for a solution but requires the addition of an observability tool, e.g. Prometheus, Grafana, or Elastic. Extending an existing pattern is not very difficult. The advantage is that it automates the integration of this extra product into pattern.   
+
+Extending usually requires four steps:
 1. Adding any required namespace for the product  
 1. Adding a subscription to install and operator
 1. Adding one or more ArgoCD applications to manage the post-install configuration of the product
 1. Adding the Helm chart needed to implement the post-install configuration identified in step 3.
 
-Sometimes there is no operator in operator hub for the product and it requires installing the product using a Helm chart. 
+Sometimes there is no operator in [OperatorHub](https://catalog.redhat.com/software/search?deployed_as=Operator) for the product and it requires installation using a Helm chart. 
 
-This additions need to be made to the appropriate `values-<cluster grouping>.yaml` file in the top level pattern directory. If the component is on a hub cluster that would be `values-hub.yaml`. If it's on a production cluster that would be in `values-production.yaml`. Look at the pattern architecture and decide where you need to add the product.
+These additions need to be made to the appropriate `values-<cluster grouping>.yaml` file in the top level pattern directory. If the component is on a hub cluster the file would be `values-hub.yaml`. If it's on a production cluster that would be in `values-production.yaml`. Look at the pattern architecture and decide where you need to add the product.
 
 In the example below AMQ Streams (Kafka) is chosen as a product to add to a pattern.
 
 ## Before starting, fork and clone first
 
 1. Visit the github page for the pattern that you wish to extend. E.g. [multicloud-gitops](https://github.com/hybrid-cloud-patterns/multicloud-gitops). Select “Fork” in the top right corner.
 
-1. On the create a new fork page. You can choose what owner repository you want and the name of the fork. Most times you will fork into your personal repo and leave the name the same. When you have made the appropriate changes press the "Create fork" button.  
+1. On the create a new fork page, you can choose what owner repository you want and the name of the fork. Most times you will fork into your personal repo and leave the name the same. When you have made the appropriate changes press the "Create fork" button.  
 
 1. You will need to clone from the new fork onto you laptop/desktop so that you can do the extension work effectively. So on the new fork’s main page elect the green “Code” button and copy the git repo’s ssh address.