(from getambassador.io) initial

reference/cluster-config.md

@@ -78,38 +78,43 @@ license configuration is required to use selective intercepts.
 
 ### Create a License
 
-First, go to [Ambassador Cloud](https://auth.datawire.io/redirects/settings/teams) and
-select *Licenses* for the team you want to create the license for. You
-can generate a new license if one doesn't already exist by clicking *Generate New License*.
+1. Go to [the teams setting page in Ambassador Cloud](https://auth.datawire.io/redirects/settings/teams) and
+select *Licenses* for the team you want to create the license for. 
 
-You will be prompted for the Cluster ID of your cluster.  To find it, ensure your
-kubeconfig context is using the cluster you want to create a license for, then
-run this command:
+2. Generate a new license (if one doesn't already exist) by clicking *Generate New License*.
+
+3. You will be prompted for your Cluster ID. Ensure your
+kubeconfig context is using the cluster you want to create a license for then
+run this command to generate the Cluster ID:
 
   ```
   $ telepresence current-cluster-id
+    
     Cluster ID: <some UID>
   ```
 
+4. Click *Generate API Key* to finish generating the license.
+
 ### Add License to Cluster
 
-On the licenses page, download the license file associated with your cluster.
-Then, use the following command to generate the license secret:
+1. On the licenses page, download the license file associated with your cluster.
 
-  ```
-  $ telepresence license -f <downloadedLicenseFile>
+2. Use this command to generate a Kubernetes Secret config using the license file:
 
+  ```
+  $ telepresence license -f <downloaded-license-file>
+    
     apiVersion: v1
     data:
-      hostDomain: <base64 encoded value>
-      license: <other base64 encoded value>
+      hostDomain: <long_string>
+      license: <longer_string>
     kind: Secret
     metadata:
       creationTimestamp: null
       name: systema-license
       namespace: ambassador
   ```
 
-Save the output as a YAML file and apply the Secret to your 
+3. Save the output as a YAML file and apply it to your 
 cluster with `kubectl`.  Once applied, you will be able to use selective intercepts with the
 `--preview-url=false` flag (since use of preview URLs requires a connection to Ambassador Cloud).

reference/docker-run.md

@@ -1,23 +1,31 @@
 ---
-Description: "How telepresence intercept can run a Docker container with configured environment and volume mounts."
+Description: "How a Telepresence intercept can run a Docker container with configured environment and volume mounts."
 ---
 
 # Using Docker for intercepts
 
-The Telepresence intercept command can automatically run a Docker container which has been configured with the environment and volume mounts of the intercepted service. This is done using the option `--docker-run`.
+If you want your intercept to go to a Docker container on your laptop, use the `--docker-run` option. It creates the intercept, runs your container in the foreground, then automatically ends the intercept when the container exits.
 
-`telepresence intercept [service] --port [port] --docker-run -- [arguments]`
+`telepresence intercept <service_name> --port <port> --docker-run -- <arguments>`
 
-This command will intercept a service and start `docker run` in the foreground. The intercept ends when the run ends.
+The `--` separates flags intended for `telepresence intercept` from flags intended for `docker run`.
 
-Telepresence will automatically pass some relevant flags to Docker in order to connect the container with the intercept. Those flags are combined with the arguments given after `--` on the command line (the `--` separates flags intended for `telepresence intercept` from flags intended for `docker run`).
+## Example 
 
-The `--port` flag can specify an additional port when `--docker-run` is used so that the local and container port can be different. This is done using `--port [local port]:[container port]`. The container port will default to the local port when using the `--port [port]` syntax
+Imagine you are working on a new version of a your frontend service.  It is running in your cluster as a Deployment called `frontend-v1`. You use Docker on your laptop to build an improved version of the container called `frontend-v2`.  To test it out, use this command to run the new container on your laptop and start an intercept of the cluster service to your local container.
 
-The flags that telepresence will pass (invisibly) to `docker run` are:
+`telepresence intercept frontend-v1 --port 8000 --docker-run -- frontend-v2`
 
-- `--dns-search tel2-search` Enables single label name lookups in intercepted namespaces.
-- `--env-file [file]` Loads the intercepted environment.
-- `--name intercept-{intercept name}-{intercept port}` Names the Docker container. This flag is omitted if explicitly given on the command line.
-- `-p [port:container-port]` The local port for the intercept and the container port.
-- `-v [local mount dir:docker mount dir]` Volume mount specification. See CLI help for `--mount` and `--docker-mount` flags for more info.
+## Ports
+
+The `--port` flag can specify an additional port when `--docker-run` is used so that the local and container port can be different. This is done using `--port <local port>:<container port>`. The container port will default to the local port when using the `--port <port>` syntax.
+
+## Flags
+
+Telepresence will automatically pass some relevant flags to Docker in order to connect the container with the intercept. Those flags are combined with the arguments given after `--` on the command line.
+
+- `--dns-search tel2-search` Enables single label name lookups in intercepted namespaces
+- `--env-file <file>` Loads the intercepted environment
+- `--name intercept-<intercept name>-<intercept port>` Names the Docker container, this flag is omitted if explicitly given on the command line
+- `-p <port:container-port>` The local port for the intercept and the container port
+- `-v <local mount dir:docker mount dir>` Volume mount specification, see CLI help for `--mount` and `--docker-mount` flags for more info