diff --git a/Makefile b/Makefile
index c37cbef542..0efc68a2e9 100644
--- a/Makefile
+++ b/Makefile
@@ -192,7 +192,7 @@ gcs-publish-ci: gcs-upload
 	echo "${GCS_URL}/${VERSION}" > .build/upload/${LATEST_FILE}
 	gsutil -h "Cache-Control:private, max-age=0, no-transform" cp .build/upload/${LATEST_FILE} ${GCS_LOCATION}
 
-gen-cli-docs:
+gen-cli-docs: kops
 	@kops genhelpdocs --out docs/cli
 
 # Will always push a linux-based build up to the server
diff --git a/docs/development/documentation.md b/docs/development/documentation.md
index 1804331486..a05dda78ea 100644
--- a/docs/development/documentation.md
+++ b/docs/development/documentation.md
@@ -4,7 +4,18 @@
 
 `kops` uses cobra for it's CLI implementation. Each command should have the following help fields defined where possible:
 
-* `Short`: single sentence description of command.
-* `Long`: expanded description and usage of the command. The text from the `Short` field should be the first sentence in the `Long` field.
-* `Example`: example(s) of how to use the command. This field is formatted as a code snippet in the docs, so make sure if you have comments
-that these are written as a bash comment (e.g. `# this is a comment`).
+* `Short`: A short statement describing the command in the third person present, starting with a capital letter and ending without a period.
+  * Example: "Edits a cluster"
+
+* `Long`: An expanded description and usage of the command in the third person present tense, starting with a capital letter and ending with a period. The text from the `Short` field should be the first sentence in the `Long` field.
+Example:
+```
+Edits a cluster.
+
+This command changes the cloud specification in the registry.
+
+It does not update the cloud resources, to apply the changes use "kops update cluster".
+```
+
+* `Example`: Example(s) of how to use the command. This field is formatted as a code snippet in the docs, so make sure if you have comments that these are written as a bash comment (e.g. `# this is a comment`).
+