Update docs/* files to incorporate k8s document style guidelines 📖

Guidelines are available here : https://kubernetes.io/docs/contribute/style/style-guide/
Guidelines applied here:
- Use present tense.
- Use active voice.
- Use simple and direct language
- Use camel case for API objects
- Avoid using "we"

Signed-off-by: Vincent Demeester <vdemeest@redhat.com>

docs/developers/README.md

@@ -5,34 +5,34 @@ the complexity.
 
 ### How are resources shared between tasks?
 
-Pipelineruns uses PVC to share resources between tasks. PVC volume is mounted on
-path `/pvc` by Pipelinerun.
+`PipelineRun` uses PVC to share resources between tasks. PVC volume is mounted on
+path `/pvc` by PipelineRun.
 
-- If resource in a task is declared as output then taskun controllers add step
-  to copy each output resource to directory path `/pvc/task_name/resource_name`.
+- If a resource in a task is declared as output then the `TaskRun` controller adds a step
+  to copy each output resource to the directory path `/pvc/task_name/resource_name`.
 
-- If input resource includes `providedBy` condition then container definition to
-  copy from PVC to directory from `/pvc/previous_task/resource_name`.
+- If an input resource includes `providedBy` condition then the `TaskRun` controller adds
+  a step to copy from PVC to directory path `/pvc/previous_task/resource_name`.
 
 ### How are inputs handled?
 
-Input resources like source code(git) or artifacts are dumped at path
+Input resources, like source code (git) or artifacts, are dumped at path
 `/workspace/task_resource_name`. Resource definition in task can have custom target directory. If
-`targetPath` is mentioned in task input then controllers have to be responsible for adding
-container definitions to create directories and also to fetch versioned
+`targetPath` is mentioned in task input then the controllers are responsible for adding
+container definitions to create directories and also to fetch the versioned
 artifacts into that directory.
 
 ### How are outputs handled?
 
-Output resources like source code(git) or artifacts(storage resource) are
+Output resources, like source code (git) or artifacts (storage resource), are
 expected in directory path `/workspace/output/resource_name`.
 
-- If resource has output "action" like upload to blob storage, then container
+- If resource has an output "action" like upload to blob storage, then the container
   step is added for this action.
-- If there is PVC volume present(taskrun holds owner reference to pipelinerun)
+- If there is PVC volume present (TaskRun holds owner reference to PipelineRun)
   then copy step is added as well.
 
-  - If resource is declared only in output but not in input for task then copy step includes resource being copied to PVC to path `/pvc/task_name/resource_name` from `/workspace/output/resource_name` like the following example.
+- If the resource is declared only in output but not in input for task then the copy step includes resource being copied to PVC to path `/pvc/task_name/resource_name` from `/workspace/output/resource_name` like the following example.
 
   ```yaml
   kind: Task
@@ -46,7 +46,7 @@ expected in directory path `/workspace/output/resource_name`.
     type: storage
   ```
 
-  - If resource is declared both in input and output for task then copy step includes resource being copied to PVC to path `/pvc/task_name/resource_name` from `/workspace/random-space/` if input resource has custom target directory(`random-space`) declared like the following example.
+- If the resource is declared both in input and output for task the then copy step includes resource being copied to PVC to path `/pvc/task_name/resource_name` from `/workspace/random-space/` if input resource has custom target directory (`random-space`) declared like the following example.
 
   ```yaml
   kind: Task
@@ -82,4 +82,4 @@ expected in directory path `/workspace/output/resource_name`.
     resources:
       - name: gcs-workspace
     type: storage
-  ```
+  ```

docs/task-parameters.md

@@ -3,10 +3,10 @@
 Tasks can declare input parameters that must be supplied to the task during a
 TaskRun. Some example use-cases of this include:
 
-- A task that needs to know what compilation flags to use when building an
+- A Task that needs to know what compilation flags to use when building an
   application.
-- A task that needs to know what to name a built artifact.
-- A task that supports several different strategies, and leaves the choice up to
+- A Task that needs to know what to name a built artifact.
+- A Task that supports several different strategies, and leaves the choice up to
   the other.
 
 ### Usage

docs/tutorial.md

@@ -1,7 +1,7 @@
 # Hello World Task
 
-The main objective of the Pipeline CRD is to run your task individually or as a
-part of a pipeline. Every task runs as a Pod on your Kubernetes cluster with
+The main objective of the Pipeline CRDs is to run your Task individually or as a
+part of a Pipeline. Every task runs as a Pod on your Kubernetes cluster with
 each step as its own container.
 
 ## Tasks
@@ -106,8 +106,8 @@ The status of type `Succeeded = True` shows the task ran successfully.
 
 # Task Inputs and Outputs
 
-In more common scenarios, your task needs multiple steps with input and output
-resources to process. For example a task could fetch source code from a GitHub
+In more common scenarios, a Task needs multiple steps with input and output
+resources to process. For example a Task could fetch source code from a GitHub
 repository and build a Docker image from it.
 
 `PipelinesResources` are used to define the artifacts that can be passed in and
@@ -144,9 +144,9 @@ spec:
       value: gcr.io/<use your project>/leeroy-web
 ```
 
-The following is a task with inputs and outputs. The input resource is a GitHub
+The following is a Task with inputs and outputs. The input resource is a GitHub
 repository and the output is the Docker image produced from that source. The
-args of the task command support templating so that the definition of task is
+args of the Task command support templating so that the definition of Task is
 constant and the value of parameters can change in runtime.
 
 ```yaml
@@ -214,14 +214,14 @@ spec:
           name: skaffold-image-leeroy-web
 ```
 
-To apply the yaml files use the following command, you will need to apply the
+To apply the yaml files use the following command, you need to apply the
 two resources, the task and taskrun.
 
 ```bash
 kubectl apply -f <name-of-file.yaml>
 ```
 
-To see all the resource created so far as part of the pipeline-crd, run the
+To see all the resource created so far as part of the Pipeline CRD, run the
 command:
 
 ```bash
@@ -242,7 +242,7 @@ NAME                                       AGE
 tasks/build-docker-image-from-git-source   7m
 ```
 
-To see the output of the taskRun, use the following command:
+To see the output of the TaskRun, use the following command:
 
 ```bash
 kubectl get taskruns/echo-hello-world-task-run -o yaml
@@ -315,14 +315,14 @@ status:
         startedAt: 2018-12-11T18:14:48Z
 ```
 
-The status of type `Succeeded = True` shows the task ran successfully and you
+The status of type `Succeeded = True` shows the Task ran successfully and you
 can also validate the Docker image is created in the location specified in the
 resource definition.
 
 # Pipeline
 
 Pipeline defines a graph of tasks to execute in a specific order, while also
-indicating if any outputs should be used as inputs of a following task by using
+indicating if any outputs should be used as inputs of a following Task by using
 the `providedBy` field. The same templating you used in tasks is also available
 in pipeline:
 
@@ -357,7 +357,7 @@ spec:
           value: "spec.template.spec.containers[0].image"
 ```
 
-This pipeline is referencing a task to `deploy-using-kubectl` which can be found
+The above Pipeline is referencing a task to `deploy-using-kubectl` which can be found
 here:
 
 ```yaml
@@ -402,7 +402,7 @@ spec:
         - "${inputs.params.path}"
 ```
 
-To run the pipeline, create a pipelineRun as follows:
+To run the Pipeline, create a PipelineRun as follows:
 
 ```yaml
 apiVersion: pipeline.knative.dev/v1alpha1
@@ -434,17 +434,17 @@ spec:
             name: skaffold-image-leeroy-web
 ```
 
-The pipelineRun will create the taskRuns corresponding to each task and collect
+The PipelineRun will create the TaskRuns corresponding to each Task and collect
 the results.
 
 To apply the yaml files use the following command, you will need to apply the
-`deploy-task` if you want to run the pipeline.
+`deploy-task` if you want to run the Pipeline.
 
 ```bash
 kubectl apply -f <name-of-file.yaml>
 ```
 
-To see the output of the pipelineRun, use the following command:
+To see the output of the PipelineRun, use the following command:
 
 ```bash
 kubectl get pipelineruns/tutorial-pipeline-run-1 -o yaml
@@ -558,4 +558,4 @@ status:
 ```
 
 The status of type `Succeeded = True` shows the pipeline ran successfully, also
-the status of individual task runs are shown.
+the status of individual Task runs are shown.

docs/using.md

@@ -23,21 +23,21 @@ See [the example Pipeline](../examples/pipeline.yaml).
 ### ProvidedBy
 
 When you need to execute `Tasks` in a particular order, it will likely be
-because they are operating over the same `Resources` (e.g. your unit test task
+because they are operating over the same `Resources` (e.g. your unit test Task
 must run first against your git repo, then you build an image from that repo,
 then you run integration tests against that image).
 
 We express this ordering by adding `providedBy` on `Resources` that our `Tasks`
 need.
 
 - The (optional) `providedBy` key on an `input source` defines a set of previous
-  task names.
+  Task names.
 - When the `providedBy` key is specified on an input source, only the version of
   the resource that is provided by the defined list of tasks is used.
-- The `providedBy` allows for `Tasks` to fan in and fan out, and ordering can be
-  expressed explicitly using this key since a task needing a resource from a
-  another task would have to run after.
-- The name used in the `providedBy` is the name of `PipelineTask`
+- The `providedBy` allows for `Task`s to fan in and fan out, and ordering can be
+  expressed explicitly using this key since a Task needing a resource from a
+  another Task would have to run after.
+- The name used in the `providedBy` is the name of `PipelineTask`.
 - The name of the `PipelineResource` must correspond to a `PipelineResource`
   from the `Task` that the referenced `PipelineTask` provides as an output
 
@@ -89,7 +89,7 @@ the `skaffold-image-leeroy-app` `PipelineResource`, and the same
 
 This controls two things:
 
-1. The order the `Tasks` are executed in: `deploy-app` must come after
+1. The order the `Task`s are executed in: `deploy-app` must come after
    `build-skaffold-app`
 2. The state of the `PipelineResources`: the image provided to `deploy-app` may
    be changed by `build-skaffold-app` (WIP, see
@@ -112,7 +112,7 @@ To create a Task, you must:
 Each container image used as a step in a [`Task`](#task) must comply with a
 specific contract.
 
-When containers are run in a `Task`, the `entrypoint` of the container will be
+When containers are run in a `Task`, the `entrypoint` of the container is
 overwritten with a custom binary that redirects the logs to a separate location
 for aggregating the log output. As such, it is always recommended to explicitly
 specify a command.
@@ -175,7 +175,7 @@ mounted under path `/pvc`.
 
 `Task` definition can include inputs and outputs resource declaration. If
 specific set of resources are only declared in output then a copy of resource to
-be uploaded or shared for next task is expected to be present under the path
+be uploaded or shared for next Task is expected to be present under the path
 `/workspace/output/resource_name/`.
 
 ```yaml
@@ -192,7 +192,7 @@ steps:
         value: "world"
 ```
 
-**Note**: If task is relying on output resource functionality then they cannot
+**Note**: If the Task is relying on output resource functionality then they cannot
 mount anything in file path `/workspace/output`.
 
 If resource is declared in both input and output then input resource, then
@@ -204,7 +204,7 @@ output so input resource is downloaded into directory `customworkspace`(as
 specified in `targetPath`). Step `untar` extracts tar file into
 `tar-scratch-space` directory , `edit-tar` adds a new file and last step
 `tar-it-up` creates new tar file and places in `/workspace/customworkspace/`
-directory. After execution of task steps, (new) tar file in directory
+directory. After execution of the Task steps, (new) tar file in directory
 `/workspace/customworkspace` will be uploaded to the bucket defined in
 `tar-artifact` resource definition.
 
@@ -445,21 +445,21 @@ secrets:
 
 ## Creating Resources
 
-We current support these `PipelineResources`:
+The following `PipelineResources` are currently supported:
 
 - [Git resource](#git-resource)
 - [Image resource](#image-resource)
 - [Cluster resource](#cluster-resource)
 - [Storage resource](#storage-resource)
 
 When used as inputs, these resources will be made available in a mounted
-directory called `/workspace` at the path /workspace/<resource-name>`.
+directory called `/workspace` at the path `/workspace/<resource-name>`.
 
 ### Git Resource
 
 Git resource represents a [git](https://git-scm.com/) repository, that contains
 the source code to be built by the pipeline. Adding the git resource as an input
-to a task will clone this repository and allow the task to perform the required
+to a Task will clone this repository and allow the Task to perform the required
 actions on the contents of the repo.
 
 To create a git resource using the `PipelineResource` CRD:
@@ -571,9 +571,9 @@ your application/function on different clusters.
 
 The resource will use the provided parameters to create a
 [kubeconfig](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/)
-file that can be used by other steps in the pipeline task to access the target
+file that can be used by other steps in the pipeline Task to access the target
 cluster. The kubeconfig will be placed in
-`/workspace/<your-cluster-name>/kubeconfig` on your task container
+`/workspace/<your-cluster-name>/kubeconfig` on your Task container
 
 The Cluster resource has the following parameters:
 
@@ -650,7 +650,7 @@ spec:
       secretName: target-cluster-secrets
 ```
 
-Example usage of the cluster resource in a task:
+Example usage of the cluster resource in a Task:
 
 ```yaml
 apiVersion: pipeline.knative.dev/v1alpha1
@@ -681,8 +681,8 @@ spec:
 ### Storage Resource
 
 Storage resource represents blob storage, that contains either an object or
-directory. Adding the storage resource as an input to a task will download the
-blob and allow the task to perform the required actions on the contents of the
+directory. Adding the storage resource as an input to a Task will download the
+blob and allow the Task to perform the required actions on the contents of the
 blob. Blob storage type
 [Google Cloud Storage](https://cloud.google.com/storage/)(gcs) is supported as
 of now.