Update docs such that they can be used in knative/docs

In version 0.4 of knative, we'd like to release build-pipeline, which
means that the docs repo (https://github.com/knative/docs) should talk
about build-pipeline.

I think it's important to make sure that docs are updated with the code,
so I propose we have living versions of these docs in this repo, and
every time we release, we copy the docs into the knative/docs repo, so
that this repo has the correct docs at HEAD and knative/docs has the
correct docs as of the latest release. (How we want to deal with docs
for previous releases will have to be another story!)

In this PR, I've gone through [the knative docs for
build](https://github.com/knative/docs/tree/master/build) and shaped our
existing docs to be similar, which meant:

* Taking content out of using.md and splitting it into a file for each
  type of CRD
* Adding reference docs for the CRD fields (fixes #193)
* Most of concepts.md and some of using.md became the README file which
  lives at the top level of the `docs` dir here and hopefully the new
  `pipelines` dir in knative/docs

This also meant gaining a lot of docs by taking existing Build docs and
updating them to talk about pipelines (e.g. docs about auth)

Fixes #304

README.md

@@ -1,8 +1,8 @@
-# ![pipe](./docs/images/pipe.png) Pipeline CRD
+# ![pipe](./pipe.png) Pipelines
 
 [![Go Report Card](https://goreportcard.com/badge/knative/build-pipeline)](https://goreportcard.com/report/knative/build-pipeline)
 
-The Pipeline CRD provides k8s-style resources for declaring CI/CD-style
+The Pipeline project provides k8s-style resources for declaring CI/CD-style
 pipelines.
 
 Pipelines are **Cloud Native**:
@@ -27,8 +27,7 @@ Pipelines are **Typed**:
 ## Want to start using Pipelines?
 
 - Jump in with [the tutorial!](docs/tutorial.md)
-- [Learn about the Concepts](/docs/Concepts.md)
-- [Read about how to use it](/docs/using.md)
+- [Read about it](/docs/README.md)
 - Look at [some examples](/examples)
 
 ## Want to contribute?

docs/README.md

@@ -0,0 +1,64 @@
+# Knative Pipelines
+
+Pipelines is an open source implementation to configure and run CI/CD style
+pipelines for your Kubernetes application.
+
+Pipeline creates
+[Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
+as building blocks to declare pipelines.
+
+A custom resource is an extension of Kubernetes API which can create a custom
+[Kubernetes Object](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#understanding-kubernetes-objects).
+Once a custom resource is installed, users can create and access its objects
+with kubectl, just as they do for built-in resources like pods, deployments etc.
+These resources run on-cluster and are implemented by
+[Kubernetes Custom Resource Definition (CRD)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions).
+
+High level details of this design:
+
+- [Pipelines](pipelines.md) do not know what will trigger them, they can be
+  triggered by events or by manually creating [PipelineRuns](pipelineruns.md)
+- [Tasks](tasks.md) can exist and be invoked completely independently of
+  [Pipelines](pipelines.md); they are highly cohesive and loosely coupled
+- [Tasks](tasks.md) can depend on artifacts, output and parameters created by other
+  tasks.
+- [Tasks](tasks.md) can be invoked via [TaskRuns](taskruns.md)
+- [PipelineResources](#pipelineresources) are the artifacts used as inputs and
+  outputs of Tasks.
+
+## Usage
+
+- [How do I create a new Pipeline?](pipelines.md)
+- [How do I make a Task?](tasks.md)
+- [How do I make Resources?](resources.md)
+- [How do I control auth?](auth.md)
+- [How do I run a Pipeline?](pipelineruns.md)
+- [How do I run a Task on its own?](taskruns.md)
+
+## Learn more
+
+See the following reference topics for information about each of the build
+components:
+
+- [`Task`](tasks.md)
+- [`TaskRun`](taskrun.md)
+- [`Pipeline`](https://github.com/knative/docs/blob/master/pipeline/pipeline.md)
+- [`PipelineRun`](https://github.com/knative/docs/blob/master/pipeline/pipelinerun.md)
+- [`PipelineResource`](https://github.com/knative/docs/blob/master/pipeline/pipelineresource.md)
+
+## Try it out
+
+* Follow along with [the tutorial](tutorial.md)
+* Look at [the examples](https://github.com/knative/build-pipeline/tree/master/examples)
+
+## Related info
+
+If you are interested in contributing to the Knative Build project, see the
+[Knative Pipeline code repository](https://github.com/knative/build-pipeline).
+
+---
+
+Except as otherwise noted, the content of this page is licensed under the
+[Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/),
+and code samples are licensed under the
+[Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0).