From ef6c7d851720cb6fcc1c8a38275c9bff8db58057 Mon Sep 17 00:00:00 2001 From: Joseph Heck Date: Tue, 13 Feb 2018 16:39:51 -0800 Subject: [PATCH] Versioning howto (#7400) * whitespace cleanup * adding word list since it keeps appearing in reviews... * initial draft based on feb13,2018 docs meeting conversation * nits --- docs/home/contribute/style-guide.md | 90 +++++++++++++++++++---------- 1 file changed, 60 insertions(+), 30 deletions(-) diff --git a/docs/home/contribute/style-guide.md b/docs/home/contribute/style-guide.md index 95f3fb3dd0..f616892d6f 100644 --- a/docs/home/contribute/style-guide.md +++ b/docs/home/contribute/style-guide.md @@ -18,12 +18,10 @@ docs, follow the instructions on **Note:** Kubernetes documentation uses [GitHub Flavored Markdown](https://github.github.com/gfm/). {: .note} - ## Language Kubernetes documentation uses US English. - ## Documentation formatting standards ### Use camel case for API objects @@ -144,24 +142,56 @@ The output is similar to this: NAME READY STATUS RESTARTS AGE IP NODE nginx 1/1 Running 0 13s 10.200.0.4 worker0 +### Versioning Kubernetes examples -{% comment %}## Kubernetes.io word list +Code examples and configuration examples that include version information should be consistent with the accompanying text. Identify the Kubernetes version in the **Before you begin** section. + +To specify the Kubernetes version for a task or tutorial page: + +- Include `min-kubernetes-server-version` in the front matter of the page. +- In the **Before you begin** section, use `{{ "{% include tasks-tutorial-prereqs.md "}} %}`. + +If the example YAML is in a standalone file, find and review the topics that include it as a reference. +Verify that any topics using the standalone YAML have the appropriate version information defined. +If a stand-alone YAML file is not referenced from any topics, consider deleting it instead of updating it. + +For example, if you are writing a tutorial that is relevant to Kubernetes version 1.8, the front-matter of your markdown file should look something like: + +```yaml +--- +title: +min-kubernetes-server-version: v1.8 +--- +``` + +In code and configuration examples, do not include comments about alternative versions. +Be careful to not include incorrect statements in your examples as comments, such as: + +```yaml +apiVersion: v1 # earlier versions use... +kind: Pod +... +``` + +## Kubernetes.io word list A list of Kubernetes-specific terms and words to be used consistently across the site. - -
TermUsage
TBDTBD
{% endcomment %} + KubernetesKubernetes should always be capitalized. + DockerDocker should always be capitalized. + SIG DocsSIG Docs rather than SIG-DOCS or other variations. + ## Callout Formatting -Callouts help create different rhetorical appeal levels. Our documentation supports three different callouts: **Note:** {: .note}, **Caution:** {: .caution}, and **Warning:** {: .warning}. +Callouts help create different rhetorical appeal levels. Our documentation supports three different callouts: **Note:** {: .note}, **Caution:** {: .caution}, and **Warning:** {: .warning}. 1. Start each callout with the appropriate prefix. 2. Use the following syntax to apply a style: - **Note:** The prefix you use is the same text you use in the tag. + **Note:** The prefix you use is the same text you use in the tag. {: .note} The output is: @@ -171,11 +201,11 @@ The output is: ### Note -Use {: .note} to highlight a tip or a piece of information that may be helpful to know. +Use {: .note} to highlight a tip or a piece of information that may be helpful to know. For example: - **Note:** You can _still_ use Markdown inside these callouts. + **Note:** You can _still_ use Markdown inside these callouts. {: .note} The output is: @@ -185,16 +215,16 @@ The output is: ### Caution -Use {: .caution} to call attention to an important piece of information to avoid pitfalls. +Use {: .caution} to call attention to an important piece of information to avoid pitfalls. For example: - **Caution:** The callout style only applies to the line directly above the tag. + **Caution:** The callout style only applies to the line directly above the tag. {: .caution} The output is: -**Caution:** The callout style only applies to the line directly above the tag. +**Caution:** The callout style only applies to the line directly above the tag. {: .caution} ### Warning @@ -203,12 +233,12 @@ Use {: .warning} to indicate danger or a piece of information that is crucial to For example: - **Warning:** Beware. + **Warning:** Beware. {: .warning} The output is: -**Warning:** Beware. +**Warning:** Beware. {: .warning} ## Common Callout Issues @@ -234,14 +264,14 @@ The output is: **Note:** This is my note. Use `
` to create multiple lines.

You can still use _Markdown_ to **format** text! {: .note} -Typing multiple lines does **not** work. The callout style only applies to the line directly above the tag. +Typing multiple lines does **not** work. The callout style only applies to the line directly above the tag. - **Note:** This is my note. + **Note:** This is my note. I didn't read the style guide. {: .note} -**Note:** This is my note. +**Note:** This is my note. I didn't read the style guide. {: .note} @@ -253,25 +283,24 @@ Callouts will interrupt numbered lists unless you indent three spaces before the For example: 1. Preheat oven to 350˚F - + 1. Prepare the batter, and pour into springform pan. - - **Note:** Grease the pan for best results. + + **Note:** Grease the pan for best results. {: .note} - + 1. Bake for 20-25 minutes or until set. - + The output is: 1. Preheat oven to 350˚F - -1. Prepare the batter, and pour into springform pan. - - **Note:** Grease the pan for best results. - {: .note} - -1. Bake for 20-25 minutes or until set. +1. Prepare the batter, and pour into springform pan. + + **Note:** Grease the pan for best results. + {: .note} + +1. Bake for 20-25 minutes or until set. ## Content best practices @@ -372,12 +401,13 @@ considered new in a few months. {% endcapture %} - {% capture whatsnext %} + * Learn about [writing a new topic](/docs/home/contribute/write-new-topic/). * Learn about [using page templates](/docs/home/contribute/page-templates/). * Learn about [staging your changes](/docs/home/contribute/stage-documentation-changes/) * Learn about [creating a pull request](/docs/home/contribute/create-pull-request/). + {% endcapture %} {% include templates/concept.md %}