docs: Fixes #8, restructure README

Update README

docs/api-updates-upgrades.md

@@ -18,11 +18,13 @@ describe how to overwrite an existing API to update the existing spec.
 
 After making the necessary changes to your manifests run the following:
 
-    operator-builder create api \
-        --workload-config [path/to/workload/config] \
-        --controller=false \
-        --resource \
-        --force
+```bash
+operator-builder create api \
+    --workload-config [path/to/workload/config] \
+    --controller=false \
+    --resource \
+    --force
+```
 
 You will pass the same workload config file.  The `--controller=false` flag will
 skip generating controller code but `--resource` and `--force` will cause the
@@ -111,7 +113,7 @@ the software when other features not related to an API are released.
 To create a new version of an existing API, update the `spec.api.version` value
 in your workload config, for example:
 
-```
+```yaml
 name: webstore
 kind: StandaloneWorkload
 spec:
@@ -130,11 +132,13 @@ spec:
 
 Now reference the config in a new `create api` command:
 
-    operator-builder create api \
-        --workload-config [path/to/workload/config] \
-        --controller \
-        --resource \
-        --force
+```bash
+operator-builder create api \
+    --workload-config [path/to/workload/config] \
+    --controller \
+    --resource \
+    --force
+```
 
 Note that we _do_ want to re-generate the controller in this case.
 A new API definition will be create alongside the previous version.  If the
@@ -143,24 +147,26 @@ version.
 
 For example if your APIs look as follows:
 
-    tree apis/apps
-    apis/apps
-    ├── v1alpha1
-    │   ├── groupversion_info.go
-    │   ├── webstore
-    │   │   ├── app.go
-    │   │   └── resources.go
-    │   ├── webstore_types.go
-    │   └── zz_generated.deepcopy.go
-    └── v1alpha2
-        ├── groupversion_info.go
-        ├── webstore
-        │   ├── app.go
-        │   └── resources.go
-        ├── webstore_types.go
-        └── zz_generated.deepcopy.go
-
-    4 directories, 10 files
+```bash
+tree apis/apps
+apis/apps
+├── v1alpha1
+│   ├── groupversion_info.go
+│   ├── webstore
+│   │   ├── app.go
+│   │   └── resources.go
+│   ├── webstore_types.go
+│   └── zz_generated.deepcopy.go
+└── v1alpha2
+    ├── groupversion_info.go
+    ├── webstore
+    │   ├── app.go
+    │   └── resources.go
+    ├── webstore_types.go
+    └── zz_generated.deepcopy.go
+
+4 directories, 10 files
+```
 
 You will delete the earlier version with `rm -rf apis/apps/v1alpha1`.
 

docs/companion-cli.md

@@ -1,6 +1,8 @@
 # Companion CLI
 
-Generate source code for a companion CLI to a Kubernetes operator.
+When you generate the source code for a Kubernetes operator with Operator
+Builder, it can include the code for a companion CLI.  The source code for the
+companion CLI will be found in the `cmd` directory of the generated codebase.
 
 The companion CLI does three things:
 1. Generate Sample Manifests: the `init` command will save a sample manifest to