From ccac3c19b851d9da8c18dbd1d6d75ece2e4faea0 Mon Sep 17 00:00:00 2001
From: Karen Bradshaw <kbhawkey@gmail.com>
Date: Wed, 14 Nov 2018 17:59:56 -0500
Subject: [PATCH] clean up conventions toc (#10939)

- clean up toc
- update with a table
---
 .../en/docs/reference/kubectl/conventions.md  | 40 ++++++++++++-------
 1 file changed, 26 insertions(+), 14 deletions(-)

diff --git a/content/en/docs/reference/kubectl/conventions.md b/content/en/docs/reference/kubectl/conventions.md
index 47890bf6fc..3e6f2d4c99 100644
--- a/content/en/docs/reference/kubectl/conventions.md
+++ b/content/en/docs/reference/kubectl/conventions.md
@@ -3,17 +3,22 @@ title: kubectl Usage Conventions
 reviewers:
 - bgrant0607
 - janetkuo
+content_template: templates/concept
 ---
 
-{{< toc >}}
+{{% capture overview %}}
+Recommended usage conventions for `kubectl`.
+{{% /capture %}}
+
+{{% capture body %}}
 
 ## Using `kubectl` in Reusable Scripts
 
 For a stable output in a script:
 
-* Request one of the machine-oriented output forms, such as `-o name`, `-o json`, `-o yaml`, `-o go-template`, or `-o jsonpath`
+* Request one of the machine-oriented output forms, such as `-o name`, `-o json`, `-o yaml`, `-o go-template`, or `-o jsonpath`.
 * Fully-qualify the version. For example, `jobs.v1.batch/myjob`. This will ensure that kubectl does not use its default version that can change over time.
-* Specify `--generator` to pin to a specific behavior forever when you use generator-based commands such as `kubectl run` or `kubectl expose`
+* Specify the `--generator` flag to pin to a specific behavior when you use generator-based commands such as `kubectl run` or `kubectl expose`.
 * Don't rely on context, preferences, or other implicit states.
 
 ## Best Practices
@@ -30,15 +35,21 @@ For `kubectl run` to satisfy infrastructure as code:
 
 #### Generators
 
-You can generate the following resources in `kubectl run`using `--generator` flag:
+You can create the following resources using `kubectl run` with the `--generator` flag:
 
-* Pod - use `run-pod/v1`.
-* Replication controller - use `run/v1`.
-* Deployment - use `extensions/v1beta1` and for an endpoint - use `deployment/v1beta1` (default).
-* Deployment - use `apps/v1beta1` and for an endpoint - use `deployment/apps.v1beta1` (recommended).
-* Job - use `job/v1`.
-* CronJob - use `batch/v1beta1`and for an endpoint - use `cronjob/v1beta1`(default).
-* CronJob - use`batch/v2alpha1` and for an endpoint - use `cronjob/v2alpha1` (deprecated).
+| Resource                        | kubectl command                                   |
+|---------------------------------|---------------------------------------------------|
+| Pod                             | `kubectl run --generator=run-pod/v1`              |
+| Replication controller          | `kubectl run --generator=run/v1`                  |
+| Deployment                      | `kubectl run --generator=extensions/v1beta1`      |
+|  -for an endpoint (default)     | `kubectl run --generator=deployment/v1beta1`      |
+| Deployment                      | `kubectl run --generator=apps/v1beta1`            |
+|  -for an endpoint (recommended) | `kubectl run --generator=deployment/apps.v1beta1` |
+| Job                             | `kubectl run --generator=job/v1`                  |
+| CronJob                         | `kubectl run --generator=batch/v1beta1`           |
+|  -for an endpoint (default)     | `kubectl run --generator=cronjob/v1beta1`         |
+| CronJob                         | `kubectl run --generator=batch/v2alpha1`          |
+|  -for an endpoint (deprecated)  | `kubectl run --generator=cronjob/v2alpha1`        |
 
 If you do not specify a generator flag, other flags prompt you to use a specific generator. The following table lists the flags that force you to use specific generators, depending on the version of the cluster:
 
@@ -59,12 +70,13 @@ This enables you to pin to a specific behavior with the generator,
 even when the default generator is changed later.
 {{< /note >}}
 
-The flags set the generator in the following order: first the schedule flag then restart policy and finally the generator.
+The flags set the generator in the following order: first the `--schedule` flag, then the `--restart` policy flag, and finally the `--generator` flag.
 
-To check the final resource that was created, use `--dry-run`
+To check the final resource that was created, use the `--dry-run`
 flag, which provides the object to be submitted to the cluster.
 
-
 ### `kubectl apply`
 
 * You can use `kubectl apply` to create or update resources. However, to update a resource you should have created the resource by using `kubectl apply` or `kubectl create --save-config`. For more information about using kubectl apply to update resources, see [Managing Resources](/docs/concepts/cluster-administration/manage-deployment/#kubectl-apply).
+
+{{% /capture %}}
\ No newline at end of file