Pipeline: Encorporate k8s documentation style guidelines

[bobcatfish]

Expected Behavior

The k8s project has a solid set of documentation guidelines. It would be great if the docs in this project followed them. This means two things:

1. We should review our existing docs (specifically READMEs) and fix any issues
2. We should add a link to these standards to our CONTRIBUTING.md

If possible we should consider adding some markdown linting as part of our

Actual Behavior

We did not follow any kind of standard when we wrote these :S

[zhyuri]

Hi, is there anyone working on this issue right now?
If not, I'm happy to do some document work.

[vdemeester]

@zhyuri I started a branch on that (https://github.com/vdemeester/build-pipeline/tree/51-take-1) but only started on Concept.md, and the more the better on docs, we may want to divide work in several pieces so different person can work on them in parallel :angel:

[zhyuri]

@vdemeester Cool! I just checked out a branch for this issue: https://github.com/zhyuri/build-pipeline/tree/issue-51 but haven't done any work yet.

Maybe we can update&check this issue before start working on new document and see if it has been worked on?

---

I tried to run this command on my Mac to compile a list of all the Markdown we have:
find . -type f -name '*.md' ! -path './vendor/*'
And here is the result.

I'm assuming all of these docs need to be checked, so I made a table to track the progress:

| File | Assignee | Status |
| ---- | ---- | ---- |
|./test/README.md | @zhyuri | Merged https://github.com/knative/build-pipeline/pull/395 |
|./test/logs/README.md | @zhyuri | WIP |
|./test/builder/README.md | @zhyuri | WIP |
|./code-of-conduct.md | @zhyuri | WIP |
|./hack/README.md | | |
|./hack/release.md | | |
|./docs/task-parameters.md | @vdemeester | Review https://github.com/knative/build-pipeline/pull/400 |
|./docs/cuj/README.md | | |
|./docs/cuj/exercises/exercise2/Exercise2.md | | |
|./docs/cuj/exercises/exercise3/Exercise3.md | | |
|./docs/cuj/exercises/exercise4/Excercise4.md | | |
|./docs/cuj/exercises/exercise1/Exercise1.md | | |
|./docs/Concepts.md | @vdemeester | Merged https://github.com/knative/build-pipeline/pull/397 |
|./docs/tutorial.md | @vdemeester | Review https://github.com/knative/build-pipeline/pull/400 |
|./docs/using.md | @vdemeester | Review https://github.com/knative/build-pipeline/pull/400 |
|./docs/developers/README.md | @vdemeester | Review https://github.com/knative/build-pipeline/pull/400 |
|./README.md | | |
|./CONTRIBUTING.md | | |
|./examples/README.md | | |
|./.github/issue-template.md | | |
|./roadmap-2019.md | | |
|./DEVELOPMENT.md | | |

I'm not sure if there is a better way to track the work. At least we can update this issue.

[bobcatfish]

I think we can consider this done for now.