docs: Reword and rephrase

docs/configuration/environment_variables.md

@@ -1,49 +1,49 @@
 ## Environment Variables
 
-The environment variables used by Piper to configure its functionality.
-The helm chart populate them using [values.yaml](https://github.com/quickube/piper/tree/main/helm-chart/values.yaml) file
+Piper uses the following environment variables to configure its functionality.
+The helm chart populates them using [values.yaml](https://github.com/quickube/piper/tree/main/helm-chart/values.yaml) file
 
 ### Git
 
 * GIT_PROVIDER
-  The git provider that Piper will use, possible variables: GitHub (will support bitbucket and gitlab)
+  The git provider that Piper will use, possible variables: GitHub . We plan to support Bitbucket and GitLab, as well.
 
 * GIT_TOKEN
-  The git token that will be used.
+  The git token that will be used to connect to the git provider.
 
 * GIT_ORG_NAME
   The organization name.
 
 * GIT_ORG_LEVEL_WEBHOOK
-  Boolean variable, whether to config webhook in organization level. default `false`
+  Boolean variable, whether to config webhook at the organization level. Defaults to `false`.
 
 * GIT_WEBHOOK_REPO_LIST
   List of repositories to configure webhooks to.
 
 * GIT_WEBHOOK_URL
-  URL of piper ingress, to configure webhooks.
+  URL of Piper ingress, to configure webhooks.
 
 * GIT_WEBHOOK_AUTO_CLEANUP
-  Will cleanup all webhook that were created with piper.
-  Notice that there will be a race conditions between pod that being terminated and the new one.
+  Boolean variable that, if true, will cause Piper to automatically cleanup all webhooks that it creates when they are no longer necessary.
+  Notice that there is a race condition between a pod that is being terminated and the new one being scheduled.
 
 * GIT_ENFORCE_ORG_BELONGING
-  Boolean variable, whether to enforce organizational belonging of git event creator. default `false`
+  Boolean variable that, if true, will cause Piper to enforce organizational belonging of git event creator. Defaults to `false`.
 
 * GIT_FULL_HEALTH_CHECK
-  Enables full health check of webhook. Full health check contains expecting and validating ping event from a webhook.
-  Doesn't work for bitbucket, because the API call doesn't exists.
+  Boolean variable that, if true, enables full health checks on webhooks. A full health check contains expecting and validating ping event from a webhook.
+  Doesn't work for Bitbucket, because the API call doesn't exist on that platform.
 
 ### Argo Workflows Server
 
 * ARGO_WORKFLOWS_TOKEN
-  The token of Argo Workflows server.
+  This token is used to authenticate with the Argo Workflows server.
 
 * ARGO_WORKFLOWS_ADDRESS
   The address of Argo Workflows Server.
 
 * ARGO_WORKFLOWS_CREATE_CRD
-  Whether to directly send Workflows instruction or create a CRD in the Cluster.
+  Boolean variable that deterines whether to directly send Workflows instructions or create a CRD in the Cluster.
 
 * ARGO_WORKFLOWS_NAMESPACE
   The namespace of Workflows creation for Argo Workflows.
@@ -56,6 +56,6 @@ The helm chart populate them using [values.yaml](https://github.com/quickube/pip
 * ROOKOUT_TOKEN
   The token used to configure Rookout agent. If not provided, will not start the agent.
 * ROOKOUT_LABELS
-  The labels to label instances at Rookout, default to "service:piper"
+  The labels to label instances at Rookout, defaults to "service:piper"
 * ROOKOUT_REMOTE_ORIGIN
   The repo URL for source code fetching, default:"https://github.com/quickube/piper.git".

docs/configuration/health_check.md

@@ -1,6 +1,6 @@
 ## Health Check
 
-Health check executed every 1 minute as configured in the helm chart under `livenessProbe`, and triggered by `/healthz` endpoint:
+The following examples shows a health check being executed every 1 minute as configured in the helm chart under `livenessProbe`, and triggered by `/healthz` endpoint:
 
 ```yaml
 livenessProbe:

docs/getting_started/installation.md

@@ -1,6 +1,6 @@
 ## Installation
 
-Piper should be deployed in the cluster with Argo Workflows.
+You must deploy Piper to a cluster with a pre-existing Argo Workflows deployment.
 Piper will create a CRD that Argo Workflows will pick, so install or configure Piper to create those CRDs in the right namespace.
 
 Please check out [values.yaml](https://github.com/quickube/piper/tree/main/helm-chart/values.yaml) file of the helm chart configurations.
@@ -24,33 +24,33 @@ helm upgrade --install piper piper/piper \
 
 ### Ingress
 
-Piper should listen to webhooks from your git provider.
-Expose it using ingress or service, then provide the address to `piper.webhook.url` as followed:
-`https://PIPER_EXPOESED_URL/webhook`
+Piper works best when it is able to listen to webhooks from your git provider.
+Expose Piper using an ingress or service, then provide the address to `piper.webhook.url` as follows:
+`https://PIPER_EXPOSEED_URL/webhook`
 
 Refer to [values.yaml](https://github.com/quickube/piper/tree/main/helm-chart/values.yaml) for more information.
 
 ### Git
 
-Piper will use git for fetching the `.workflows` folder and receiving events using webhooks.
+Piper will use git to fetch the `.workflows` folder and receive events using webhooks.
 
-To pick which git provider you are using provide `gitProvider.name` configuration in helm chart (Now only supports GitHub and Bitbucket).
+To pick which git provider you are using provide `gitProvider.name` configuration in helm chart (Currently we only support GitHub and Bitbucket).
 
-Also configure you organization (Github) or workspace (Bitbucket) name using `gitProvider.organization.name` in helm chart.
+You must also configure your organization (GitHub) or workspace (Bitbucket) name using `gitProvider.organization.name` in the helm chart.
 
 #### Git Token Permissions
 
 The token should have access for creating webhooks and read repositories content.
-For GitHub configure `admin:org` and `write:org` permissions in Classic Token.
-For Bitbucket configure `Repositories:read`, `Webhooks:read and write` and `Pull requests:read` permissions (for multiple repos use workspace token).
+For GitHub, configure `admin:org` and `write:org` permissions in Classic Token.
+For Bitbucket, configure `Repositories:read`, `Webhooks:read and write` and `Pull requests:read` permissions (for multiple repos use workspace token).
 
 #### Token
 
 The git token should be passed as secret in the helm chart at `gitProvider.token`.
-Can be passed as parameter in helm install command using `--set piper.gitProvider.token=YOUR_GIT_TOKEN`
+The token can be passed as parameter via helm install command using `--set piper.gitProvider.token=YOUR_GIT_TOKEN`
 
-Alternatively, you can consume already existing secret and fill up `piper.gipProvider.existingSecret`.
-The key should be name `token`. Can be created using
+Alternatively, you can consume an already existing secret by configuring `piper.gipProvider.existingSecret`.
+The key should have the name `token`. You can be create a Secret using this command:
 
 ```bash
 kubectl create secret generic piper-git-token --from-literal=token=YOUR_GIT_OKEN
@@ -60,9 +60,9 @@ kubectl create secret generic piper-git-token --from-literal=token=YOUR_GIT_OKEN
 
 Piper will create a webhook configuration for you, for the whole organization or for each repo you configure.
 
-Configure `piper.webhook.url` the address of piper that exposed with ingress with `/webhook` postfix.
+Configure `piper.webhook.url` with the address of Piper that you exposed using an Ingress or Service with `/webhook` postfix.
 
-For organization level configure: `gitProvider.webhook.orgLevel` to `true`.
+For organization level configuration: `gitProvider.webhook.orgLevel` to `true`.
 
 For granular repo webhook provide list of repos at: `gitProvider.webhook.repoList`.
 

docs/index.md

@@ -3,19 +3,17 @@
 <p align="center">
   <img src="https://www.quickube.com/wp-content/uploads/2022/10/ArgoPipeline_1.0_Hero.png.webp?raw=true" />
 </p>
-
-Welcome to Piper! 
 
-Piper is an open source project that aimed at providing multibranch pipeline functionality to Argo Workflows, allows users to create distinct Workflows based on Git branches. Supports GitHub and Bitbucket.
+Welcome to Piper!
 
-## General explanation
+Piper is an open source project that aimed at providing multibranch pipeline functionality to Argo Workflows. This allows users to create distinct Workflows based on Git branches. We supports GitHub and Bitbucket.
+
+## General Explanation
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/quickube/piper/main/docs/img/flow.svg" />
 </p>
 
-To achieve multibranch pipeline functionality Piper will do the hard works for us.
-At initialization, it will load all configuration and create a webhook in repository or organization scope.
-Then each branch that have `.workflows` folder will create a Workflow CRD out of the files in this folder.
+Piper handles the hard work of configuring multibranch pipelines for us! At initialization, it will load all configuration and create a webhook in repository or organization scope. Then, for each branch that has a `.workflows` folder, Piper will create a Workflow CRD out of the files in this folder. Finally, when Piper detects changes in the repository via the webhook, it triggers the workflows that match the branch and event.
 
-![type:video](./img/piper-demo-1080.mp4)
+![type:video](./img/piper-demo-1080.mp4)