update readme

Signed-off-by: Ahmet Alp Balkan <ahmetb@google.com>

Author: ahmetb

README.md

@@ -1,27 +1,52 @@
-# Knative API Reference Docs generator
+# Kubernetes Custom Resource API Reference Docs generator
 
-## Why?
+If you have a project that is Custom Resource Definitions and wanted to generate
+API Reference Docs [like this][ar] this tool is for you.
 
-Normally we would want to use [Kubernetes API
-reference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/)
-which is auto-generated. But for the time being, Kubernetes API does not provide
-OpenAPI specs for CRDs (e.g. Knative), therefore we cannot use the same
-generator.
+[ar]: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/
 
-Proposal for generating API Reference docs for Knative:
-https://github.com/knative/docs/issues/636.
+## Why
 
-## How?
+Normally you would want to use the same [docs generator][dg] as [Kubernetes API
+reference][ar], but here's why I wrote a different parser/generator:
 
-This is a custom API Reference Docs generator that uses the
+1. Today, Kubernetes API [does not][pr] provide OpenAPI specs for CRDs (e.g.
+   Knative), therefore the [gen-apidocs][ga]
+   generator used by Kubernetes won't work.
+
+2. Even when Kubernetes API starts providing OpenAPI specs for CRDs, your CRD
+   must have a validation schema (e.g. Knative API doesn't!)
+
+3. Kubernetes [gen-apidocs][ga] parser relies on running a `kube-apiserver` and
+   calling `/apis` endpoint to get OpenAPI specs to generate docs. **This tool
+   doesn't need that!**
+
+[dg]: https://github.com/kubernetes-incubator/reference-docs/
+[ga]: https://github.com/kubernetes-incubator/reference-docs/tree/master/gen-apidocs/generators
+[pr]: https://github.com/kubernetes/kubernetes/pull/71192
+
+## How
+
+This is a custom API reference docs generator that uses the
 [k8s.io/gengo](https://godoc.org/k8s.io/gengo) project to parse types and
 generate API documentation from it.
 
+Capabilities of this tool include:
+
+- Doesn't depend on OpenAPI specs, or kube-apiserver, or a running cluster.
+- Relies only on the Go source code (pkg/apis/**/*.go) to parse API types.
+- Can link to other sites for external APIs. For example, if your types have a
+  reference to Kubernetes core/v1.PodSpec, you can link to it.
+- [Configurable](./example-config.json) settings to hide certain fields or types
+  entirely from the generated output.
+- Either output to a file or start a live http-server (for rapid iteration).
+
 ## Try it out
 
 1. Clone this repository.
 
-2. Make sure you have go1.11+ instaled.
+2. Make sure you have go1.11+ instaled. Then run `go build`, you should get a
+   `refdocs` binary executable.
 
 3. Clone a Knative repository, set GOPATH correctly,
    and call the compiled binary within that directory.
@@ -31,8 +56,8 @@ generate API documentation from it.
     # goclone(1) to have a separate GOPATH for each repo I clone.)
     $ goclone knative/build
 
-    $ refdocs \
-        -config "/path/to/knative-config.json" \
+    $ /path/to/refdocs \
+        -config "/path/to/example-config.json" \
         -api-dir "github.com/knative/build/pkg/apis/build/v1alpha1" \
         -out-file docs.html
     ```