|
|
|
@@ -14,10 +14,10 @@ This page gives writing style guidelines for the Kubernetes documentation.
|
|
|
|
|
These are guidelines, not rules. Use your best judgment, and feel free to
|
|
|
|
|
propose changes to this document in a pull request.
|
|
|
|
|
|
|
|
|
|
For additional information on creating new content for the Kubernetes
|
|
|
|
|
documentation, read the [Documentation Content
|
|
|
|
|
Guide](/docs/contribute/style/content-guide/) and follow the instructions on
|
|
|
|
|
[using page templates](/docs/contribute/style/page-templates/) and [creating a
|
|
|
|
|
For additional information on creating new content for the Kubernetes
|
|
|
|
|
documentation, read the [Documentation Content
|
|
|
|
|
Guide](/docs/contribute/style/content-guide/) and follow the instructions on
|
|
|
|
|
[using page templates](/docs/contribute/style/page-templates/) and [creating a
|
|
|
|
|
documentation pull request](/docs/contribute/start/#improve-existing-content).
|
|
|
|
|
|
|
|
|
|
{{% /capture %}}
|
|
|
|
@@ -58,11 +58,11 @@ leads to an awkward construction.
|
|
|
|
|
{{< table caption = "Do and Don't - API objects" >}}
|
|
|
|
|
Do | Don't
|
|
|
|
|
:--| :-----
|
|
|
|
|
The Pod has two containers. | The pod has two containers.
|
|
|
|
|
The Pod has two containers. | The pod has two containers.
|
|
|
|
|
The Deployment is responsible for ... | The Deployment object is responsible for ...
|
|
|
|
|
A PodList is a list of Pods. | A Pod List is a list of pods.
|
|
|
|
|
The two ContainerPorts ... | The two ContainerPort objects ...
|
|
|
|
|
The two ContainerStateTerminated objects ... | The two ContainerStateTerminateds ...
|
|
|
|
|
The two ContainerPorts ... | The two ContainerPort objects ...
|
|
|
|
|
The two ContainerStateTerminated objects ... | The two ContainerStateTerminateds ...
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@@ -83,11 +83,11 @@ represents.
|
|
|
|
|
Do | Don't
|
|
|
|
|
:--| :-----
|
|
|
|
|
Click **Fork**. | Click "Fork".
|
|
|
|
|
Select **Other**. | Select "Other".
|
|
|
|
|
Select **Other**. | Select "Other".
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
|
|
|
|
|
### Use italics to define or introduce new terms
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
{{< table caption = "Do and Don't - Use italics for new terms" >}}
|
|
|
|
|
Do | Don't
|
|
|
|
|
:--| :-----
|
|
|
|
@@ -102,7 +102,7 @@ Do | Don't
|
|
|
|
|
:--| :-----
|
|
|
|
|
Open the `envars.yaml` file. | Open the envars.yaml file.
|
|
|
|
|
Go to the `/docs/tutorials` directory. | Go to the /docs/tutorials directory.
|
|
|
|
|
Open the `/_data/concepts.yaml` file. | Open the /_data/concepts.yaml file.
|
|
|
|
|
Open the `/_data/concepts.yaml` file. | Open the /\_data/concepts.yaml file.
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
|
|
|
|
|
### Use the international standard for punctuation inside quotes
|
|
|
|
@@ -119,18 +119,18 @@ The copy is called a "fork". | The copy is called a "fork."
|
|
|
|
|
### Use code style for inline code and commands
|
|
|
|
|
|
|
|
|
|
For inline code in an HTML document, use the `<code>` tag. In a Markdown
|
|
|
|
|
document, use the backtick (`).
|
|
|
|
|
document, use the backtick (`` ` ``).
|
|
|
|
|
|
|
|
|
|
{{< table caption = "Do and Don't - Use code style for inline code and commands" >}}
|
|
|
|
|
Do | Don't
|
|
|
|
|
:--| :-----
|
|
|
|
|
The `kubectl run`command creates a Deployment. | The "kubectl run" command creates a Deployment.
|
|
|
|
|
For declarative management, use `kubectl apply`. | For declarative management, use "kubectl apply".
|
|
|
|
|
Enclose code samples with triple backticks. `(```)`| Enclose code samples with any other syntax.
|
|
|
|
|
Use single backticks to enclose inline code. For example, `var example = true`. | Use two asterisks (**) or an underscore (_) to enclose inline code. For example, **var example = true**.
|
|
|
|
|
Enclose code samples with triple backticks. (\`\`\`)| Enclose code samples with any other syntax.
|
|
|
|
|
Use single backticks to enclose inline code. For example, `var example = true`. | Use two asterisks (`**`) or an underscore (`_`) to enclose inline code. For example, **var example = true**.
|
|
|
|
|
Use triple backticks before and after a multi-line block of code for fenced code blocks. | Use multi-line blocks of code to create diagrams, flowcharts, or other illustrations.
|
|
|
|
|
Use meaningful variable names that have a context. | Use variable names such as 'foo','bar', and 'baz' that are not meaningful and lack context.
|
|
|
|
|
Remove trailing spaces in the code. | Add trailing spaces in the code, where these are important, because the screen reader will read out the spaces as well.
|
|
|
|
|
Remove trailing spaces in the code. | Add trailing spaces in the code, where these are important, because the screen reader will read out the spaces as well.
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
|
|
|
|
|
{{< note >}}
|
|
|
|
@@ -185,7 +185,7 @@ Do | Don't
|
|
|
|
|
Set the value of `imagePullPolicy` to Always. | Set the value of `imagePullPolicy` to "Always".
|
|
|
|
|
Set the value of `image` to nginx:1.16. | Set the value of `image` to `nginx:1.16`.
|
|
|
|
|
Set the value of the `replicas` field to 2. | Set the value of the `replicas` field to `2`.
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Code snippet formatting
|
|
|
|
@@ -196,7 +196,7 @@ Set the value of the `replicas` field to 2. | Set the value of the `replicas` fi
|
|
|
|
|
Do | Don't
|
|
|
|
|
:--| :-----
|
|
|
|
|
kubectl get pods | $ kubectl get pods
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Separate commands from output
|
|
|
|
@@ -214,7 +214,7 @@ The output is similar to this:
|
|
|
|
|
|
|
|
|
|
Code examples and configuration examples that include version information should be consistent with the accompanying text.
|
|
|
|
|
|
|
|
|
|
If the information is version specific, the Kubernetes version needs to be defined in the `prerequisites` section of the [Task template](/docs/contribute/style/page-templates/#task-template) or the [Tutorial template] (/docs/contribute/style/page-templates/#tutorial-template). Once the page is saved, the `prerequisites` section is shown as **Before you begin**.
|
|
|
|
|
If the information is version specific, the Kubernetes version needs to be defined in the `prerequisites` section of the [Task template](/docs/contribute/style/page-templates/#task-template) or the [Tutorial template](/docs/contribute/style/page-templates/#tutorial-template). Once the page is saved, the `prerequisites` section is shown as **Before you begin**.
|
|
|
|
|
|
|
|
|
|
To specify the Kubernetes version for a task or tutorial page, include `min-kubernetes-server-version` in the front matter of the page.
|
|
|
|
|
|
|
|
|
@@ -251,11 +251,11 @@ Kubernetes | Kubernetes should always be capitalized.
|
|
|
|
|
Docker | Docker should always be capitalized.
|
|
|
|
|
SIG Docs | SIG Docs rather than SIG-DOCS or other variations.
|
|
|
|
|
On-premises | On-premises or On-prem rather than On-premise or other variations.
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
|
|
|
|
|
## Shortcodes
|
|
|
|
|
|
|
|
|
|
Hugo [Shortcodes](https://gohugo.io/content-management/shortcodes) help create different rhetorical appeal levels. Our documentation supports three different shortcodes in this category: **Note** {{</* note */>}}, **Caution** {{</* caution */>}}, and **Warning** {{</* warning */>}}.
|
|
|
|
|
Hugo [Shortcodes](https://gohugo.io/content-management/shortcodes) help create different rhetorical appeal levels. Our documentation supports three different shortcodes in this category: **Note** `{{</* note */>}}`, **Caution** `{{</* caution */>}}`, and **Warning** `{{</* warning */>}}`.
|
|
|
|
|
|
|
|
|
|
1. Surround the text with an opening and closing shortcode.
|
|
|
|
|
|
|
|
|
@@ -275,7 +275,7 @@ The prefix you choose is the same text for the tag.
|
|
|
|
|
|
|
|
|
|
### 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:
|
|
|
|
|
|
|
|
|
@@ -291,7 +291,7 @@ The output is:
|
|
|
|
|
You can _still_ use Markdown inside these callouts.
|
|
|
|
|
{{< /note >}}
|
|
|
|
|
|
|
|
|
|
You can use a {{</* note */>}} in a list:
|
|
|
|
|
You can use a `{{</* note */>}}` in a list:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
1. Use the note shortcode in a list
|
|
|
|
@@ -323,7 +323,7 @@ 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:
|
|
|
|
|
|
|
|
|
@@ -341,7 +341,7 @@ The callout style only applies to the line directly above the tag.
|
|
|
|
|
|
|
|
|
|
### Warning
|
|
|
|
|
|
|
|
|
|
Use {{</* warning */>}} to indicate danger or a piece of information that is crucial to follow.
|
|
|
|
|
Use `{{</* warning */>}}` to indicate danger or a piece of information that is crucial to follow.
|
|
|
|
|
|
|
|
|
|
For example:
|
|
|
|
|
|
|
|
|
@@ -359,11 +359,11 @@ Beware.
|
|
|
|
|
|
|
|
|
|
### Katacoda Embedded Live Environment
|
|
|
|
|
|
|
|
|
|
This button lets users run Minikube in their browser using the [Katacoda Terminal](https://www.katacoda.com/embed/panel).
|
|
|
|
|
It lowers the barrier of entry by allowing users to use Minikube with one click instead of going through the complete
|
|
|
|
|
This button lets users run Minikube in their browser using the [Katacoda Terminal](https://www.katacoda.com/embed/panel).
|
|
|
|
|
It lowers the barrier of entry by allowing users to use Minikube with one click instead of going through the complete
|
|
|
|
|
Minikube and Kubectl installation process locally.
|
|
|
|
|
|
|
|
|
|
The Embedded Live Environment is configured to run `minikube start` and lets users complete tutorials in the same window
|
|
|
|
|
The Embedded Live Environment is configured to run `minikube start` and lets users complete tutorials in the same window
|
|
|
|
|
as the documentation.
|
|
|
|
|
|
|
|
|
|
{{< caution >}}
|
|
|
|
@@ -376,7 +376,7 @@ For example:
|
|
|
|
|
{{</* kat-button */>}}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The output is:
|
|
|
|
|
The output is:
|
|
|
|
|
|
|
|
|
|
{{< kat-button >}}
|
|
|
|
|
|
|
|
|
@@ -391,7 +391,7 @@ 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 */>}}
|
|
|
|
|
`{{</* note */>}}Grease the pan for best results.{{</* /note */>}}`
|
|
|
|
|
|
|
|
|
|
1. Bake for 20-25 minutes or until set.
|
|
|
|
|
|
|
|
|
@@ -429,9 +429,9 @@ Do | Don't
|
|
|
|
|
:--| :-----
|
|
|
|
|
Update the title in the front matter of the page or blog post. | Use first level heading, as Hugo automatically converts the title in the front matter of the page into a first-level heading.
|
|
|
|
|
Use ordered headings to provide a meaningful high-level outline of your content. | Use headings level 4 through 6, unless it is absolutely necessary. If your content is that detailed, it may need to be broken into separate articles.
|
|
|
|
|
Use pound or hash signs (#) for non-blog post content. | Use underlines (--- or ===) to designate first-level headings.
|
|
|
|
|
Use pound or hash signs (`#`) for non-blog post content. | Use underlines (`---` or `===`) to designate first-level headings.
|
|
|
|
|
Use sentence case for headings. For example, **Extend kubectl with plugins** | Use title case for headings. For example, **Extend Kubectl With Plugins**
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
|
|
|
|
|
### Paragraphs
|
|
|
|
|
|
|
|
|
@@ -439,8 +439,8 @@ Use sentence case for headings. For example, **Extend kubectl with plugins** | U
|
|
|
|
|
Do | Don't
|
|
|
|
|
:--| :-----
|
|
|
|
|
Try to keep paragraphs under 6 sentences. | Indent the first paragraph with space characters. For example, ⋅⋅⋅Three spaces before a paragraph will indent it.
|
|
|
|
|
Use three hyphens (---) to create a horizontal rule. Use horizontal rules for breaks in paragraph content. For example, a change of scene in a story, or a shift of topic within a section. | Use horizontal rules for decoration.
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
Use three hyphens (`---`) to create a horizontal rule. Use horizontal rules for breaks in paragraph content. For example, a change of scene in a story, or a shift of topic within a section. | Use horizontal rules for decoration.
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
|
|
|
|
|
### Links
|
|
|
|
|
|
|
|
|
@@ -449,7 +449,7 @@ Do | Don't
|
|
|
|
|
:--| :-----
|
|
|
|
|
Write hyperlinks that give you context for the content they link to. For example: Certain ports are open on your machines. See <a href="#check-required-ports">Check required ports</a> for more details. | Use ambiguous terms such as “click here”. For example: Certain ports are open on your machines. See <a href="#check-required-ports">here</a> for more details.
|
|
|
|
|
Write Markdown-style links: `[link text](URL)`. For example: `[Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/#table-captions)` and the output is [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/#table-captions). | Write HTML-style links: `<a href="/media/examples/link-element-example.css" target="_blank">Visit our tutorial!</a>`, or create links that open in new tabs or windows. For example: `[example website](https://example.com){target="_blank"}`
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Lists
|
|
|
|
@@ -457,17 +457,17 @@ Group items in a list that are related to each other and need to appear in a spe
|
|
|
|
|
Website navigation links can also be marked up as list items; after all they are nothing but a group of related links.
|
|
|
|
|
|
|
|
|
|
- End each item in a list with a period if one or more items in the list are complete sentences. For the sake of consistency, normally either all items or none should be complete sentences.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
{{< note >}} Ordered lists that are part of an incomplete introductory sentence can be in lowercase and punctuated as if each item was a part of the introductory sentence.{{< /note >}}
|
|
|
|
|
|
|
|
|
|
- Use the number one (1.) for ordered lists.
|
|
|
|
|
|
|
|
|
|
- Use (+), (* ), or (-) for unordered lists.
|
|
|
|
|
|
|
|
|
|
- Leave a blank line after each list.
|
|
|
|
|
|
|
|
|
|
- Indent nested lists with four spaces (for example, ⋅⋅⋅⋅).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- Use the number one (`1.`) for ordered lists.
|
|
|
|
|
|
|
|
|
|
- Use (`+`), (`*`), or (`-`) for unordered lists.
|
|
|
|
|
|
|
|
|
|
- Leave a blank line after each list.
|
|
|
|
|
|
|
|
|
|
- Indent nested lists with four spaces (for example, ⋅⋅⋅⋅).
|
|
|
|
|
|
|
|
|
|
- List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either four spaces or one tab.
|
|
|
|
|
|
|
|
|
|
### Tables
|
|
|
|
@@ -486,7 +486,7 @@ This section contains suggested best practices for clear, concise, and consisten
|
|
|
|
|
Do | Don't
|
|
|
|
|
:--| :-----
|
|
|
|
|
This command starts a proxy. | This command will start a proxy.
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Exception: Use future or past tense if it is required to convey the correct
|
|
|
|
@@ -512,7 +512,7 @@ Use simple and direct language. Avoid using unnecessary phrases, such as saying
|
|
|
|
|
Do | Don't
|
|
|
|
|
:--| :-----
|
|
|
|
|
To create a ReplicaSet, ... | In order to create a ReplicaSet, ...
|
|
|
|
|
See the configuration file. | Please see the configuration file.
|
|
|
|
|
See the configuration file. | Please see the configuration file.
|
|
|
|
|
View the Pods. | With this next command, we'll view the Pods.
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
|
|
|
|
@@ -522,7 +522,7 @@ View the Pods. | With this next command, we'll view the Pods.
|
|
|
|
|
Do | Don't
|
|
|
|
|
:--| :-----
|
|
|
|
|
You can create a Deployment by ... | We'll create a Deployment by ...
|
|
|
|
|
In the preceding output, you can see... | In the preceding output, we can see ...
|
|
|
|
|
In the preceding output, you can see... | In the preceding output, we can see ...
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@@ -583,7 +583,7 @@ considered new in a few months.
|
|
|
|
|
Do | Don't
|
|
|
|
|
:--| :-----
|
|
|
|
|
In version 1.4, ... | In the current version, ...
|
|
|
|
|
The Federation feature provides ... | The new Federation feature provides ...
|
|
|
|
|
The Federation feature provides ... | The new Federation feature provides ...
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
vineeth