Restructure Docs (#421)

README.md

@@ -1,7 +1,6 @@
 # Knative Client
 
-This section outlines best practices for the Knative developer experience, is a reference for Knative CLI
+This section outlines best practices for the Knative developer experience. It is a reference for Knative CLI implementation, and a reference for Knative client libraries.
-implementation, and a reference for Knative client libraries.
 
 The goals of the Knative Client are to:
 
@@ -16,7 +15,6 @@ The goals of the Knative Client are to:
 Start with the [user's guide](docs/README.md) to learn more. You can read about common use cases, get detailed documentation on each command, and learn how to extend the `kn` CLI. For more information, access the following links:
 
 * [User's guide](docs/README.md)
-* [Basic workflows](docs/workflows.md) (use cases)
 * [Generated documentation](docs/cmd/kn.md)
 
 **Bash auto completion:**

docs/README.md

@@ -30,72 +30,24 @@ You'll need a `kubectl`-style config file to connect to your cluster.
  * Instructions for Red Hat [OpenShift](https://docs.openshift.com/container-platform/4.1/cli_reference/administrator-cli-commands.html#create-kubeconfig).
  * Or contact your cluster administrator.
 
-`kn` will pick up your `kubectl` config file in the default location of
+`kn` will pick up your `kubectl` config file in the default location of `$HOME/.kube/config`. You can specify an alternate kubeconfig connection file with `--kubeconfig`, or the env var `$KUBECONFIG`, for any command.
-`$HOME/.kube/config`. You can specify an alternate kubeconfig connection file
+
-with `--kubeconfig`, or the env var `$KUBECONFIG`, for any command.
+----------------------------------------------------------
 
 ## Commands
 
-See the [generated documentation](cmd/kn.md)
+* See the [generated documentation](cmd/kn.md) 
+* See the documentation on [managing `kn`](operations/management.md)
 
-### Service Management
 
-A Knative service is the embodiment of a serverless workload. It is generally in the form of a collection of containers running in a group of pods, in the underlying Kubernetes cluster. Each Knative service associates with a collection of revisions, which represent the evolution of that service.
+## Plugins
 
-With the Kn CLI a user can [`list`](cmd/kn_service_list.md), [`create`](cmd/kn_service_create.md), [`delete`](cmd/kn_service_delete.md), and [`update`](cmd/kn_service_update.md) Knative services. The [detail reference](cmd/kn_service.md) of each sub-command under the [`service`](cmd/kn_service.md) command shows the options and flags for this group of commands.
+Kn supports plugins, which allow you to extend the functionality of your `kn` installation with custom commands as well as shared commands that are not part of the core distribution of `kn`. See the [plugins documentation](plugins/README.md) for more information.
 
-Examples:
 
-```bash
+## More information on `kn`:
-# Create a new service from an image
 
-kn service create mysvc --env KEY1=VALUE1 --env KEY2=VALUE2 --image dev.local/ns/image:latest
+* [Workflows](workflows/README.md)
-```
+* [Operations](operations/README.md)
+* [Traffic Splitting](traffic/README.md)
 
-You are able to also specify the requests and limits of both CPU and memory when creating a service. See [`service create`](cmd/kn_service_create.md) command reference for additional details.
-
-```bash
-# List existing services in the 'default' namespace of your cluster
-
-kn service list
-```
-
-You can also list services from all namespaces or a specific namespace using flags: `--all-namespaces` and `--namespace mynamespace`. See [`service list`](cmd/kn_service_list.md) command reference for additional details.
-
-### Revision Management
-
-A Knative revision is a "snapshot" of the specification of a service. For instance, when a Knative service is created with the environment variable `FOO=bar` a revision is added to the service. Afterwards, when the environment variable is changed to `baz` or additional variables are added, a new revision is created. When the image that the service is running is changed to a new digest, a new revision is created.
-
-With the [`revision`](cmd/kn_revision.md) command group you can [list](cmd/kn_revision_list.md) and [describe](cmd/kn_revision_describe.md) the current revisions on a service.
-
-Examples:
-
-```bash
-# Listing a service's revision
-
-kn revision list --service srvc # CHECK this since current command does not have --service flag
-```
-
-### Plugins
-
-Kn supports plugins, which allow you to extend the functionality of your Kn installation with custom commands as well as shared commands that are not part of the core distribution of Kn. 
-
-Plugins follow a similar architecture to [kubectl plugins](https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/) with some small differences. One key difference is that Kn plugins can either live in your `PATH` or in a chosen and specified directory. [Kn plugins](plugins.md) shows how to install and create new plugins as well as giving some examples and best practices.
-
-To see what plugins are installed on your machine, you can use the [`plugin`](cmd/kn_plugin.md) command group's [`list`](cmd/kn_plugin_list.md) command.
-
-### Utilities
-
-These are commands that provide some useful information to the user.
-
-* The `kn help` command displays a list of the commands with helpful information.
-* The [`kn version`](cmd/kn_version.md) command will display the current version of the `kn` build including date and Git commit revision.
-* The `kn completion` command will output a BASH completion script for `kn` to allow command completions with tabs.
-
-### Common Flags
-
-For every Kn command you can use these optional common additional flags:
-
-* `-h` or `--help` to display specific help for that command
-* `--config string` which specifies the Kn config file (default is $HOME/.kn.yaml)
-* `--kubeconfig string` which specifies the kubectl config file (default is $HOME/.kube/config)

docs/cmd/kn_plugin.md

@@ -4,9 +4,10 @@ Plugin command group
 
 ### Synopsis
 
-Provides utilities for interacting and managing with kn plugins.
+Provides utilities for interacting and managing with `kn` plugins.
+
+Plugins provide extended functionality that is not part of the core `kn` command-line distribution.
 
-Plugins provide extended functionality that is not part of the core kn command-line distribution.
 Please refer to the documentation and examples for more information about how write your own plugins.
 
 ```
@@ -33,4 +34,3 @@ kn plugin [flags]
 
 * [kn](kn.md)	 - Knative client
 * [kn plugin list](kn_plugin_list.md)	 - List plugins
-

docs/operations/README.md

@@ -0,0 +1,8 @@
+# Operations
+
+
+* [Autoscaling](autoscaling.md)
+* [Labeling](labeling.md)
+* [Management](management.md)
+* [Resources](resources.md)
+* [All others](others.md)

docs/operations/autoscaling.md

@@ -0,0 +1,19 @@
+# Autoscaling
+
+The Knative Pod Autoscaler (KPA), provides fast, request-based autoscaling capabilities. To correctly configure autoscaling to zero for revisions, you must modify its paramenters.
+
+`target` defines how many concurrent requests are wanted at a given time (soft limit) and is the recommended configuration for autoscaling in Knative.
+
+The `minScale` and `maxScale` annotations can be used to configure the minimum and maximum number of pods that can serve applications.
+
+You can access autoscaling capabilities by using `kn` to modify Knative services without editing YAML files directly.
+
+Use the `service create` and `service update` commands with the appropriate flags to configure the autoscaling behavior.
+
+
+ Flag | Description|
+:------|:-----------|
+| `--concurrency-limit int`| Hard limit of concurrent requests to be processed by a single replica.
+| `--concurrency-target int`| Recommendation for when to scale up based on the concurrent number of incoming requests. Defaults to `--concurrency-limit`.
+| `--max-scale int`| Maximum number of replicas.
+| `--min-scale int`| Minimum number of replicas. 

docs/operations/management.md

@@ -0,0 +1,57 @@
+# Management Commands
+
+## Service Management
+
+A Knative service is the embodiment of a serverless workload. It is generally in the form of a collection of containers running in a group of pods, in the underlying Kubernetes cluster. Each Knative service associates with a collection of revisions, which represent the evolution of that service.
+
+With the Kn CLI a user can [`list`](../cmd/kn_service_list.md), [`create`](../cmd/kn_service_create.md), [`delete`](../cmd/kn_service_delete.md), and [`update`](../cmd/kn_service_update.md) Knative services. The [detail reference](../cmd/kn_service.md) of each sub-command under the [`service`](../cmd/kn_service.md) command shows the options and flags for this group of commands.
+
+Examples:
+
+```bash
+# Create a new service from an image
+
+kn service create mysvc --env KEY1=VALUE1 --env KEY2=VALUE2 --image dev.local/ns/image:latest
+```
+
+You are able to also specify the requests and limits of both CPU and memory when creating a service. See [`service create`](../cmd/kn_service_create.md) command reference for additional details.
+
+```bash
+# List existing services in the 'default' namespace of your cluster
+
+kn service list
+```
+
+You can also list services from all namespaces or a specific namespace using flags: `--all-namespaces` and `--namespace mynamespace`. See [`service list`](../cmd/kn_service_list.md) command reference for additional details.
+
+
+## Revision Management
+
+A Knative revision is a "snapshot" of the specification of a service. For instance, when a Knative service is created with the environment variable `FOO=bar` a revision is added to the service. Afterwards, when the environment variable is changed to `baz` or additional variables are added, a new revision is created. When the image that the service is running is changed to a new digest, a new revision is created.
+
+With the [`revision`](../cmd/kn_revision.md) command group you can [list](../cmd/kn_revision_list.md) and [describe](../cmd/kn_revision_describe.md) the current revisions on a service.
+
+Examples:
+
+```bash
+# Listing a service's revision
+
+kn revision list --service srvc # CHECK this since current command does not have --service flag
+```
+
+## Utilities
+
+These are commands that provide some useful information to the user.
+
+* The `kn help` command displays a list of the commands with helpful information.
+* The [`kn version`](../cmd/kn_version.md) command will display the current version of the `kn` build including date and Git commit revision.
+* The `kn completion` command will output a BASH completion script for `kn` to allow command completions with tabs.
+
+
+## Common Flags
+
+For every Kn command you can use these optional common additional flags:
+
+* `-h` or `--help` to display specific help for that command
+* `--config string` which specifies the Kn config file (default is $HOME/.kn.yaml)
+* `--kubeconfig string` which specifies the kubectl config file (default is $HOME/.kube/config)

docs/operations/others.md

@@ -0,0 +1 @@
+TODO

docs/operations/resources.md

@@ -0,0 +1 @@
+TODO

docs/plugins/README.md

@@ -0,0 +1,11 @@
+# `kn` Plugins
+
+Plugins follow a similar architecture to [kubectl plugins](https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/) with some small differences. One key difference is that `kn` plugins can either live in your `PATH` or in a chosen and specified directory. [Kn plugins](https://github.com/knative/client/tree/master/docs/cmd/kn_plugin.md) shows how to install and create new plugins as well as gives some examples and best practices.
+
+To see what plugins are installed on your machine, you can use the [`plugin`](https://github.com/knative/client/tree/master/docs/cmd/kn_plugin.md) command group's [`list`](https://github.com/knative/client/tree/master/docs/cmd/kn_plugin_list.md) command.
+
+Plugins provide extended functionality that is not part of the core `kn` command-line distribution.
+
+Please refer to the documentation and examples for more information on how to write your own plugins.
+
+* [kn plugin](../cmd/kn_plugin.md)	 - Plugin command group

docs/traffic/README.md

@@ -0,0 +1,8 @@
+# Traffic Splitting
+
+kn can help you control which revisions get traffic in your Knative Service.
+
+A Knative Service has a traffic mapping, which is a mapping of revisions of the Service to percent amounts of traffic, along with the ability to create unique URLs for particular revisions. It also has the ability to assign traffic to the latest Revision, which can change as new revisions are created.
+
+* [Traffic Operations](revisions.md)
+* [Examples](examples.md)

docs/traffic/examples.md

@@ -0,0 +1,66 @@
+# Traffic Splitting Examples
+
+1. Tag revisions `echo-v1` and `echo-v2` as `stable` and `staging` respectively:
+```
+kn service update svc --tag echo-v1=stable --tag echo-v2=staging
+```
+
+2. Ramp up/down revision `echo-v3` to `20%`, adjusting other traffic to accommodate:
+```
+kn service update svc --traffic echo-v3=20 --traffic echo-v2=80
+```
+
+3. Give revision `echo-v3` tag `candidate`, without otherwise changing any traffic split:
+```
+kn service update svc --tag echo-v3=candidate
+```
+
+4. Give `echo-v3` tag `candidate`, and `2%` of traffic adjusting other traffic to go to revision `echo-v2`:
+```
+kn service update svc --tag echo-v3=candidate --traffic candidate=2 --traffic echo-v2=98
+```
+
+6. Update tag for `echo-v3` from `candidate` to `current`:
+```
+kn service update svc --untag candidate --tag echo-v3=current
+```
+
+7. Remove tag `current` from `echo-v3`:
+```
+kn service update svc --untag current
+```
+
+8. Remove `echo-v3` having no tag(s) entirely, adjusting `echo-v2` to fill up:
+```
+kn service update svc --traffic echo-v2=100    # a target having no-tags or no-traffic gets removed
+```
+
+9. Remove `echo-v1` and its tag `old` from the traffic assignments entirely:
+```
+kn service update svc --untag old --traffic echo-v1=0
+```
+
+10. Tag revision `echo-v1` with `stable` as well as `current`, and `50-50%` traffic split to each:
+```
+kn service update svc --tag echo-v1=stable,echo-v2=current --traffic stable=50,current=50
+```
+
+11. Revert all the traffic to the latest ready revision of service:
+```
+kn service update svc --traffic @latest=100
+```
+
+12. Tag latest ready revision of service as `current`:
+```
+kn service update svc --tag @latest=current
+```
+
+13. Update tag for `echo-v4` to `testing` and assign all traffic to it:
+```
+kn service update svc --untag oldv4 --tag echo-v4=testing --traffic testing=100
+```
+
+14. Update `latest` tag of `echo-v1` with `old` tag, give `latest` to `echo-v2`:
+```
+kn service update svc --untag latest --tag echo-v1=old --tag echo-v2=latest
+```

docs/traffic/revisions.md

@@ -1,14 +1,8 @@
-# Traffic Splitting
+# Traffic Operations
-
-kn can help you control which revisions get traffic in your Knative Service.
-
-A Knative Service has a traffic mapping, which is a mapping of revisions of the Service to percent amounts of traffic, along with the ability to create unique URLs for particular revisions. It also has the ability to assign traffic to the latest Revision, which can change as new revisions are created.
-
-## Operations
 
 `kn` supports the following traffic operations on traffic block of a Service as part of `kn service update` command.
 
-### 1. Split Traffic:
+## Split Traffic
 
 Every time you update the Service's template, a new Revision is created with 100% traffic routing to it. With every update to the Configuration of the
 Service, a new Revision is created with Service route pointing all the traffic to the latest ready Revision by default.
@@ -17,7 +11,7 @@ For example, you might want to carefully roll out 10% of traffic to your new Rev
 
 Updating the traffic is performed by `kn service update` with the `--traffic` flag.
 
-- **`--traffic RevisionName=Percent`**
+**`--traffic RevisionName=Percent`**
   - `--traffic` flag requires two values separated by a `=`
   - `RevisionName` string refers to name of Revision and `Percent` integer denotes the traffic portion to assign for this Revision
   - `Percent` integer denotes the traffic portion to assign to the this Revision
@@ -26,12 +20,13 @@ Updating the traffic is performed by `kn service update` with the `--traffic` fl
   - `--traffic` flag can be specified multiple times and is valid only if the sum of `Percent` values in all flags add up to 100
   - Example: `kn service update svc --traffic @latest=10 --traffic svc-vwxyz=90`
 
-### 2. Tag Revisions:
+
+### Tag Revisions
 A tag in traffic block of Service creates a custom URL, which points to the referenced Revision.
 A user can define a unique tag for an available Revision of the Service thereby generating a custom URL of format `http(s)://TAG-SERVICE.DOMAIN`.
 A given tag must be unique in traffic block of the Service. `kn` supports assigning and unassigning custom tags for revisions of the Service as part of `kn service update` command as follow:
 
-- **`--tag RevisionName=Tag`**
+**`--tag RevisionName=Tag`**
   - `--tag` flag requires two values separated by a `=`
   - `RevisionName` string refers to name of the `Revision`
   - `Tag` string denotes the custom tag to be given for this Revision
@@ -46,18 +41,20 @@ A given tag must be unique in traffic block of the Service. `kn` supports assign
 - User can specify `--traffic` and `--tag` flags in same `service update` command and allowed to use the new tag for Revision reference
   for eg: `kn service update svc --tag echo-abcde=stable --traffic stable=100`.
 
-### 3. Untag Revisions:
+
+### Untag Revisions:
 Assigned tags to revisions in traffic block can be unassigned, thereby removing any custom URLs. A user can unassign the tags for revisions as part of `kn service update` command as follow:
 
-- **`--untag Tag`**
+**`--untag Tag`**
   - `--untag` flag requires one value
   - `tag` string denotes the unique tag in traffic block of the Service which needs to be unassigned and thereby also removing respective custom URL
   - `--untag` flag can be specified multiple times
   - Example: `kn service update svc --untag candidate`
 
-*Note*:
+**_NOTE_**:
 - If a Revision is untagged and it is assigned 0% of the traffic, it is removed from the traffic block entirely.
 
+
 ## Flag operation precedence
 - All the traffic-related flags can bespecified together in a single `kn service update` command, thus `kn` defines the precedence of these flags in which operations are evaluated.
 - The order of the flags specified in the command are **not** taken into account.
@@ -67,7 +64,7 @@ Assigned tags to revisions in traffic block can be unassigned, thereby removing
 2. `--tag`: Second, all the revisions are tagged as specified in the traffic block
 3. `--traffic`: Third, all the referenced revisions (or tags) are assigned given portion of traffic split
 
-*Note*:
+**_NOTE_**:
 - Use comma separated value pairs or separate value pairs:
   For example: `--tag echo-v1=v1,echo-v2=v2` is same as `--tag echo-v1=v1 --tag echo-v2=v2`
   similarly, `--traffic v1=50,v2=50` is same as `--traffic v1=50 --traffic v2=50`
@@ -102,68 +99,3 @@ Flag | Value(s) | Operation | Repetition
 `--untag` | `Tag` | Remove `Tag` from Revision | :heavy_check_mark:
 
 
-## Examples
-1. Tag revisions `echo-v1` and `echo-v2` as `stable` and `staging` respectively:
-```
-kn service update svc --tag echo-v1=stable --tag echo-v2=staging
-```
-
-2. Ramp up/down revision `echo-v3` to `20%`, adjusting other traffic to accommodate:
-```
-kn service update svc --traffic echo-v3=20 --traffic echo-v2=80
-```
-
-3. Give revision `echo-v3` tag `candidate`, without otherwise changing any traffic split:
-```
-kn service update svc --tag echo-v3=candidate
-```
-
-4. Give `echo-v3` tag `candidate`, and `2%` of traffic adjusting other traffic to go to revision `echo-v2`:
-```
-kn service update svc --tag echo-v3=candidate --traffic candidate=2 --traffic echo-v2=98
-```
-
-6. Update tag for `echo-v3` from `candidate` to `current`:
-```
-kn service update svc --untag candidate --tag echo-v3=current
-```
-
-7. Remove tag `current` from `echo-v3`:
-```
-kn service update svc --untag current
-```
-
-8. Remove `echo-v3` having no tag(s) entirely, adjusting `echo-v2` to fill up:
-```
-kn service update svc --traffic echo-v2=100    # a target having no-tags or no-traffic gets removed
-```
-
-9. Remove `echo-v1` and its tag `old` from the traffic assignments entirely:
-```
-kn service update svc --untag old --traffic echo-v1=0
-```
-
-10. Tag revision `echo-v1` with `stable` as well as `current`, and `50-50%` traffic split to each:
-```
-kn service update svc --tag echo-v1=stable,echo-v2=current --traffic stable=50,current=50
-```
-
-11. Revert all the traffic to the latest ready revision of service:
-```
-kn service update svc --traffic @latest=100
-```
-
-12. Tag latest ready revision of service as `current`:
-```
-kn service update svc --tag @latest=current
-```
-
-13. Update tag for `echo-v4` to `testing` and assign all traffic to it:
-```
-kn service update svc --untag oldv4 --tag echo-v4=testing --traffic testing=100
-```
-
-14. Update `latest` tag of `echo-v1` with `old` tag, give `latest` to `echo-v2`:
-```
-kn service update svc --untag latest --tag echo-v1=old --tag echo-v2=latest
-```

docs/workflows/README.md

@@ -0,0 +1,7 @@
+# Workflows
+
+This section of lists the common workflows and use-cases for the Knative CLI. This is a live document, meant to be updated as we learn more about good ways to use `kn`.
+
+To learn more, see information on:
+
+* [Basic workflows](basic.md)

docs/workflows/basic.md

@@ -1,8 +1,4 @@
-# Workflows
+# Basic Workflow
-
-The purpose of this section of the Kn documentation is to list common workflows or use-cases for the Knative CLI. This is a live document, meant to be updated as we learn more about good ways to use `kn`.
-
-## Basic
 
 In this basic worflow we show the CRUD (create, read, update, delete) operations on a service. We use a well known [simple Hello World service](https://github.com/knative/docs/tree/master/docs/serving/samples/hello-world/helloworld-go) that reads the environment variable `TARGET` and prints it as output.
 
@@ -13,7 +9,7 @@ kn service create hello --image gcr.io/knative-samples/helloworld-go --env TARGE
 Service 'hello' successfully created in namespace 'default'.
 ```
 
-* **List service**
+* **List a service**
 
 ```bash
 kn service list hello
@@ -30,7 +26,7 @@ Hello Knative!
 
 Where `http://xxx.xx.xxx.xx` is your Knative installation ingress.
 
-* **Update service**
+* **Update a service**
 
 ```bash
 kn service update hello --env TARGET=Kn
@@ -38,7 +34,7 @@ kn service update hello --env TARGET=Kn
 
 The service's environment variable `TARGET` is now set to `Kn`.
 
-* **Describe service**
+* **Describe a service**
 
 ```bash
 kn service describe hello
@@ -91,7 +87,7 @@ status:
     revisionName: hello-00001
 ```
 
-* **Delete service**
+* **Delete a service**
 
 ```bash
 kn service delete hello