docs: Documentation Improvements (quickube#23)

* docs: Proofreading and some MD linting

* docs: Reword and rephrase

* Update docs/getting_started/installation.md

---------

Co-authored-by: Brandon High <759848+highb@users.noreply.github.com>
Co-authored-by: GoshaDo <86723475+GoshaDo@users.noreply.github.com>

README.md

@@ -5,16 +5,18 @@ Welcome to Piper! Piper is open source project that aimed at providing multibran
 
 ## Table of Contents
 
-- [Getting Started](#getting-started)
-- [Reporting Issues](#reporting-issues)
-- [How to Contribute](docs/CONTRIBUTING.md#how-to-contribute)
-- [License](#license)
+- [Piper](#piper)
+  - [Table of Contents](#table-of-contents)
+  - [Getting Started](#getting-started)
+  - [Reporting Issues](#reporting-issues)
+  - [How to Contribute](#how-to-contribute)
+  - [License](#license)
 
 ## Getting Started
 
-Piper configures a webhook in git provider and listens to the webhooks sends. It will create a Workflow CRD out of branches that contains `.workflows` folder. 
-This folder should contain declarations of the templates and main DAG that will be running. 
-Finally, it will submit the Workflow as a K8s resource in the cluster. 
+Piper configures a webhook in git provider and listens to the webhooks sends. It will create a Workflow CRD out of branches that contains `.workflows` folder.
+This folder should contain declarations of the templates and main DAG that will be running.
+Finally, it will submit the Workflow as a K8s resource in the cluster.
 To access more detailed explanations, please navigate to the [Documentation site](https://piper.quickube.com).
 
 https://github.com/quickube/piper/assets/106976988/09b3a5d8-3428-4bdc-9146-3034d81164bf
@@ -29,7 +31,6 @@ If you encounter any issues or bugs while using Piper, please help us improve by
 4. Add appropriate labels to categorize the issue (e.g., bug, enhancement, question).
 5. Submit the issue, and our team will review and address it as soon as possible.
 
-
 ## How to Contribute
 
 If you're interested in contributing to this project, please feel free to submit a pull request. We welcome all contributions and feedback.
@@ -38,6 +39,3 @@ Please check out our [Contribution guidelines for this project](docs/CONTRIBUTIN
 ## License
 
 This project is licensed under the Apache License. Please see the [LICENSE](LICENSE) file for details.
-
-
-

docs/configuration/environment_variables.md

@@ -1,7 +1,7 @@
 ## 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
 

docs/configuration/health_check.md

@@ -1,6 +1,7 @@
 ## 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:
   httpGet:
@@ -18,14 +19,13 @@ The mechanism for checking the health of Piper is:
 
 1. Piper set health status of all webhooks to not-healthy.
 
-2. Piper requests ping from all the webhooks configured. 
+2. Piper requests ping from all the webhooks configured.
 
 3. Git Provider send ping to `/webhook` endpoint, this will set the health status to `healthy` with timeout of 5 seconds.
 
 4. Piper check the status of all webhooks configured.
 
 Therefore, the criteria for health checking are:
-1. The registered webhook exists. 
-2. The webhook send a ping in 5 seconds.
-
 
+1. The registered webhook exists.
+2. The webhook send a ping in 5 seconds.

docs/getting_started/installation.md

@@ -1,4 +1,4 @@
-## Instalation
+## Installation
 
 Piper should be deployed in the cluster with Argo Workflows.
 Piper will create a CRD that Argo Workflows will pick, so install or configure Piper to create those CRDs in the right namespace.
@@ -28,11 +28,11 @@ 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`
 
-Checkout [values.yaml](https://github.com/quickube/piper/tree/main/helm-chart/values.yaml)
+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 `.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 (supports GitHub, Bitbucket and Gitlab).
 
@@ -41,8 +41,8 @@ Also configure you organization (Github), workspace (Bitbucket) or group (Gitlab
 #### 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
 
@@ -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)

docs/usage/global_variables.md

@@ -1,4 +1,4 @@
-## Global variables
+## Global Variables
 
 Piper will automatically add Workflow scope parameters that can be referenced from any template.
 The parameters taken from webhook metadata, and will be populated respectively to GitProvider and event that triggered the workflow.

docs/usage/workflows_config.md

@@ -5,15 +5,18 @@ Piper can inject configuration for Workflows that Piper creates.
 `default` config used as a convention for all Workflows that piper will create, even if not explicitly mentioned in triggers.yaml file.
 
 ### ConfigMap
+
 Piper will mount a configMap when helm used.
 `piper.workflowsConfig` variable in helm chart, will create a configMap that hold set of configuration for Piper.
 Here is an [examples](https://github.com/quickube/piper/tree/main/examples/config.yaml) of such configuration.
 
 ### Spec
-This will be injected to Workflow spec field. can hold all configuration of the Workflow. 
+
+This will be injected to Workflow spec field. can hold all configuration of the Workflow.
 > :warning: Please notice that the fields `entrypoint` and `onExit` should not exist in spec. both of them are managed fields.
 
 ### onExit
-This is the exit handler for each of the Workflows create by piper. 
-It configures a DAG that will be executed when the workflow ends. 
-You can provide the templates to it us in the following [Examples](https://github.com/quickube/piper/tree/main/examples/config.yaml).
+
+This is the exit handler for each of the Workflows create by piper.
+It configures a DAG that will be executed when the workflow ends.
+You can provide the templates to it us in the following [Examples](https://github.com/quickube/piper/tree/main/examples/config.yaml).

docs/usage/workflows_folder.md

@@ -5,8 +5,9 @@ We will explain each of the files that should be included in the `.workflows` fo
 
 ### triggers.yaml (convention name)
 
-This file holds a list of triggers that will be executed `onStart` by `events` from specific `branches`. 
+This file holds a list of triggers that will be executed `onStart` by `events` from specific `branches`.
 Piper will execute each of matching triggers, so configure it wisely.
+
 ```yaml
 - events:
     - push
@@ -17,50 +18,57 @@ Piper will execute each of matching triggers, so configure it wisely.
   templates: ["templates.yaml"]
   config: "default"
 ```
-Can be found [here](https://github.com/quickube/piper/tree/main/examples/.workflows/triggers.yaml).
+
+This example can be found [here](https://github.com/quickube/piper/tree/main/examples/.workflows/triggers.yaml).
 
 In this example `main.yaml` will be executed as DAG when `push` or `pull_request.synchronize` events will be applied in `main` branch.
 `onExit` will be executed `exit.yaml` when finished the workflow as exit handler.
 
-
 `onExit` can overwrite the default `onExit` configuration from by reference existing DAG tasks as in the [example](https://github.com/quickube/piper/tree/main/examples/.workflows/exit.yaml).
 
 `config` field used for workflow configuration selection. the default value is `default` configuration.
 
 #### events
-Events field used to terminate when the trigger will be executed. name of the event depends on the git provider. 
+
+Events field used to terminate when the trigger will be executed. name of the event depends on the git provider.
 
 For instance, GitHub pull_request event have few action, one of them is synchronize.
 
 #### branches
+
 For which branch that trigger will be executed.
 
-####  onStart
+#### onStart
+
 This [file](https://github.com/quickube/piper/tree/main/examples/.workflows/main.yaml) can be named as you wish and will be referenced in `triggers.yaml` file. It will define an entrypoint DAG that the Workflow will execute.
 
 As a best practice, this file should contain the dependencies logic and parametrization of each of referenced templates. It should not implement new templates, for this, use template.yaml file.
 
-####  onExit
+#### onExit
+
 This field used to pass verbose exitHandler to the triggered workflow.
 It will override the default onExit from the provided `config` or the default `config`.
 
 In the provided `exit.yaml` describes a DAG that will overwrite the default `onExit` configuration.
 [Example](https://github.com/quickube/piper/tree/main/examples/.workflows/exit.yaml)
 
-####  templates
-This field will have additional templates that will be injected to the workflows. 
+#### templates
+
+This field will have additional templates that will be injected to the workflows.
 The purpose of this field is to create repository scope templates that can be referenced from the DAGs templates at `onStart` or `onExit`.
 [Example](https://github.com/quickube/piper/tree/main/examples/.workflows/templates.yaml)
 
 As a best practice, use this field for template implementation and reference them from executed.
 [Example](https://github.com/quickube/piper/tree/main/examples/.workflows/main.yaml).
 
 ### config
-configured by `piper-workflows-config` [configMap](workflows_config.md). 
+
+configured by `piper-workflows-config` [configMap](workflows_config.md).
 Can be passed explicitly, or will use `deafault` configuration.
 
 ###  parameters.yaml (convention name)
-Will hold a list of global parameters of the Workflow. 
-can be referenced from any template with `{{ workflow.parameters.___ }}.`
 
-[Example](https://github.com/quickube/piper/tree/main/examples/.workflows/parameters.yaml)
+Will hold a list of global parameters of the Workflow.
+Can be referenced from any template with `{{ workflow.parameters.___ }}.`
+
+[Example](https://github.com/quickube/piper/tree/main/examples/.workflows/parameters.yaml)

examples/.workflows/templates.yaml

@@ -6,5 +6,5 @@
     image: alpine
     command: [ sh ]
     source: |
-      echo "wellcome to {{ workflow.parameters.global }}
-      echo "{{ inputs.parameters.message }}"
+      echo "welcome to {{ workflow.parameters.global }}
+      echo "{{ inputs.parameters.message }}"

examples/config.yaml

@@ -24,10 +24,10 @@ data:
           key: node_pool
           operator: Equal
           value: workflows
-    onExit: # optinal, will be overwritten if specifc in .wokrflows/exit.yaml.
+    onExit: # optional, will be overwritten if specifc in .workflows/exit.yaml.
       - name: github-status
         template: exit-handler
         arguments:
           parameters:
             - name: param1
-              value: "{{ workflow.labels.repo }}"
+              value: "{{ workflow.labels.repo }}"

examples/workflow.yaml

@@ -19,7 +19,7 @@ spec:
   archiveLogs: true
   arguments:
     parameters:
-      - name: PLACHOLDER
+      - name: PLACEHOLDER
   artifactRepositoryRef:
     configMap: artifact-repositories
   onExit: exit-handler
@@ -50,7 +50,7 @@ spec:
       image: alpine
       command: [sh]
       source: |
-        echo "wellcome to {{ workflow.parameters.global }}
+        echo "welcome to {{ workflow.parameters.global }}
         echo "{{ inputs.parameters.message }}"
   - name: exit-handler
     script:
@@ -75,6 +75,3 @@ spec:
             value: step-2
         dependencies:
         - local-step1
-
-
-