| Do | Don't |
|---|---|
| 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 ... |
| Do | Don't |
|---|---|
| Click Fork. | Click "Fork". |
| Select Other. | Select 'Other'. |
| Do | Don't |
|---|---|
| A cluster is a set of nodes ... | A "cluster" is a set of nodes ... |
| These components form the control plane. | These components form the control plane. |
| 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. |
| Do | Don't |
|---|---|
| events are recorded with an associated "stage". | events are recorded with an associated "stage." |
| The copy is called a "fork". | The copy is called a "fork." |
` tag. In a Markdown
document, use the backtick (`).
-
- 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**. 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.
+{{< 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**.
+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.
+{{< /table >}}
{{< note >}}
The website supports syntax highlighting for code samples, but specifying a language is optional. Syntax highlighting in the code block should conform to the [contrast guidelines.](https://www.w3.org/WAI/WCAG21/quickref/?versions=2.0&showtechniques=141%2C143#contrast-minimum)
@@ -129,31 +139,36 @@ The website supports syntax highlighting for code samples, but specifying a lang
### Use code style for object field names
-
- Do Don't Set the value of the replicas field in the configuration file. Set the value of the "replicas" field in the configuration file. The value of the exec field is an ExecAction object. The value of the "exec" field is an ExecAction object.
+{{< table caption = "Do and Don't - Use code style for object field names" >}}
+Do | Don't
+:--| :-----
+Set the value of the `replicas` field in the configuration file. | Set the value of the "replicas" field in the configuration file.
+The value of the `exec` field is an ExecAction object. | The value of the "exec" field is an ExecAction object.
+{{< /table >}}
### Use normal style for string and integer field values
For field values of type string or integer, use normal style without quotation marks.
-
- 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.8. Set the value of image to nginx:1.8. Set the value of the replicas field to 2. Set the value of the replicas field to 2.
+{{< table caption = "Do and Don't - Use normal style for string and integer field values" >}}
+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.8. | Set the value of `image` to `nginx:1.8`.
+Set the value of the `replicas` field to 2. | Set the value of the `replicas` field to `2`.
+{{< /table >}}
+
## Code snippet formatting
### Don't include the command prompt
-
- Do Don't kubectl get pods $ kubectl get pods
+{{< table caption = "Do and Don't - Don't include the command prompt" >}}
+Do | Don't
+:--| :-----
+kubectl get pods | $ kubectl get pods
+{{< /table >}}
+
### Separate commands from output
@@ -200,13 +215,14 @@ kind: Pod
A list of Kubernetes-specific terms and words to be used consistently across the site.
-
- Term Usage 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 caption = "Kubernetes.io word list" >}}
+Term | Usage
+:--- | :----
+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 >}}
## Shortcodes
@@ -379,26 +395,33 @@ Use a single newline to separate block-level content like headings, lists, image
### Headings
People accessing this documentation may use a screen reader or other assistive technology (AT). [Screen readers](https://en.wikipedia.org/wiki/Screen_reader) are linear output devices, they output items on a page one at a time. If there is a lot of content on a page, you can use headings to give the page an internal structure. A good page structure helps all readers to easily navigate the page or filter topics of interest.
-
- 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 sentence case for headings. For example, Extend kubectl with plugins Use title case for headings. For example, Extend Kubectl With Plugins
+{{< table caption = "Do and Don't - Headings" >}}
+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 sentence case for headings. For example, **Extend kubectl with plugins** | Use title case for headings. For example, **Extend Kubectl With Plugins**
+{{< /table >}}
### Paragraphs
-
- 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 caption = "Do and Don't - Paragraphs" >}}
+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 >}}
### Links
-
- 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 Check required ports for more details. Use ambiguous terms such as “click here”. For example: Certain ports are open on your machines. See here 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. Write HTML-style links (<link href="/media/examples/link-element-example.css" target="_blank">Visit our tutorial!) or create links that open in new tabs or windows. For example, [example website](https://example.com){target="_blank"}
+
+{{< table caption = "Do and Don't - Links" >}}
+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 Check required ports for more details. | Use ambiguous terms such as “click here”. For example: Certain ports are open on your machines. See here 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: `Visit our tutorial!`, or create links that open in new tabs or windows. For example: `[example website](https://example.com){target="_blank"}`
+{{< /table >}}
+
### Lists
Group items in a list that are related to each other and need to appear in a specific order or to indicate a correlation between multiple items. When a screen reader comes across a list—whether it is an ordered or unordered list—it will be announced to the user that there is a group of list items. The user can then use the arrow keys to move up and down between the various items in the list.
@@ -430,21 +453,25 @@ This section contains suggested best practices for clear, concise, and consisten
### Use present tense
-
- Do Don't This command starts a proxy. This command will start a proxy.
+{{< table caption = "Do and Don't - Use present tense" >}}
+Do | Don't
+:--| :-----
+This command starts a proxy. | This command will start a proxy.
+ {{< /table >}}
+
Exception: Use future or past tense if it is required to convey the correct
meaning.
### Use active voice
-
- Do Don't You can explore the API using a browser. The API can be explored using a browser. The YAML file specifies the replica count. The replica count is specified in the YAML file.
+{{< table caption = "Do and Don't - Use active voice" >}}
+Do | Don't
+:--| :-----
+You can explore the API using a browser. | The API can be explored using a browser.
+The YAML file specifies the replica count. | The replica count is specified in the YAML file.
+{{< /table >}}
+
Exception: Use passive voice if active voice leads to an awkward construction.
@@ -452,31 +479,35 @@ Exception: Use passive voice if active voice leads to an awkward construction.
Use simple and direct language. Avoid using unnecessary phrases, such as saying "please."
-
- Do Don't To create a ReplicaSet, ... In order to create a ReplicaSet, ... See the configuration file. Please see the configuration file. View the Pods. With this next command, we'll view the Pods.
+{{< table caption = "Do and Don't - Use simple and direct language" >}}
+Do | Don't
+:--| :-----
+To create a ReplicaSet, ... | In order to create a ReplicaSet, ...
+See the configuration file. | Please see the configuration file.
+View the Pods. | With this next command, we'll view the Pods.
+{{< /table >}}
### Address the reader as "you"
-
- 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 ...
+{{< table caption = "Do and Don't - Addressing the reader" >}}
+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 ...
+{{< /table >}}
+
### Avoid Latin phrases
Prefer English terms over Latin abbreviations.
-
- Do Don't For example, ... e.g., ... That is, ... i.e., ...
+{{< table caption = "Do and Don't - Avoid Latin phrases" >}}
+Do | Don't
+:--| :-----
+For example, ... | e.g., ...
+That is, ...| i.e., ...
+{{< /table >}}
+
Exception: Use "etc." for et cetera.
@@ -487,22 +518,26 @@ Exception: Use "etc." for et cetera.
Using "we" in a sentence can be confusing, because the reader might not know
whether they're part of the "we" you're describing.
-
- Do Don't Version 1.4 includes ... In version 1.4, we have added ... Kubernetes provides a new feature for ... We provide a new feature ... This page teaches you how to use Pods. In this page, we are going to learn about Pods.
+{{< table caption = "Do and Don't - Patterns to avoid" >}}
+Do | Don't
+:--| :-----
+Version 1.4 includes ... | In version 1.4, we have added ...
+Kubernetes provides a new feature for ... | We provide a new feature ...
+This page teaches you how to use Pods. | In this page, we are going to learn about Pods.
+{{< /table >}}
+
### Avoid jargon and idioms
Some readers speak English as a second language. Avoid jargon and idioms to help them understand better.
-
- Do Don't Internally, ... Under the hood, ... Create a new cluster. Turn up a new cluster.
+{{< table caption = "Do and Don't - Avoid jargon and idioms" >}}
+Do | Don't
+:--| :-----
+Internally, ... | Under the hood, ...
+Create a new cluster. | Turn up a new cluster.
+{{< /table >}}
+
### Avoid statements about the future
@@ -515,11 +550,13 @@ information.
Avoid words like "currently" and "new." A feature that is new today might not be
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 ...
+{{< table caption = "Do and Don't - Avoid statements that will soon be out of date" >}}
+Do | Don't
+:--| :-----
+In version 1.4, ... | In the current version, ...
+The Federation feature provides ... | The new Federation feature provides ...
+{{< /table >}}
+
{{% /capture %}}
diff --git a/content/en/docs/contribute/style/write-new-topic.md b/content/en/docs/contribute/style/write-new-topic.md
index 98f70cc7d4d62..8a5d7949e4f9a 100644
--- a/content/en/docs/contribute/style/write-new-topic.md
+++ b/content/en/docs/contribute/style/write-new-topic.md
@@ -19,24 +19,13 @@ Create a fork of the Kubernetes documentation repository as described in
As you prepare to write a new topic, think about the page type that would fit your content the best:
-
-
-
- Concept
- A concept page explains some aspect of Kubernetes. For example, a concept page might describe the Kubernetes Deployment object and explain the role it plays as an application while it is deployed, scaled, and updated. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials. For an example of a concept topic, see Nodes.
-
-
-
- Task
- A task page shows how to do a single thing. The idea is to give readers a sequence of steps that they can actually do as they read the page. A task page can be short or long, provided it stays focused on one area. In a task page, it is OK to blend brief explanations with the steps to be performed, but if you need to provide a lengthy explanation, you should do that in a concept topic. Related task and concept topics should link to each other. For an example of a short task page, see Configure a Pod to Use a Volume for Storage. For an example of a longer task page, see Configure Liveness and Readiness Probes
-
-
-
- Tutorial
- A tutorial page shows how to accomplish a goal that ties together several Kubernetes features. A tutorial might provide several sequences of steps that readers can actually do as they read the page. Or it might provide explanations of related pieces of code. For example, a tutorial could provide a walkthrough of a code sample. A tutorial can include brief explanations of the Kubernetes features that are being tied together, but should link to related concept topics for deep explanations of individual features.
-
-
-
+{{< table caption = "Guidelines for choosing a page type" >}}
+Type | Description
+:--- | :----------
+Concept | A concept page explains some aspect of Kubernetes. For example, a concept page might describe the Kubernetes Deployment object and explain the role it plays as an application while it is deployed, scaled, and updated. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials. For an example of a concept topic, see Nodes.
+Task | A task page shows how to do a single thing. The idea is to give readers a sequence of steps that they can actually do as they read the page. A task page can be short or long, provided it stays focused on one area. In a task page, it is OK to blend brief explanations with the steps to be performed, but if you need to provide a lengthy explanation, you should do that in a concept topic. Related task and concept topics should link to each other. For an example of a short task page, see Configure a Pod to Use a Volume for Storage. For an example of a longer task page, see Configure Liveness and Readiness Probes
+Tutorial | A tutorial page shows how to accomplish a goal that ties together several Kubernetes features. A tutorial might provide several sequences of steps that readers can actually do as they read the page. Or it might provide explanations of related pieces of code. For example, a tutorial could provide a walkthrough of a code sample. A tutorial can include brief explanations of the Kubernetes features that are being tied together, but should link to related concept topics for deep explanations of individual features.
+{{< /table >}}
Use a template for each new page. Each page type has a
[template](/docs/contribute/style/page-templates/)