|
|
|
@@ -55,14 +55,16 @@ PodTemplateList, not Pod Template List.
|
|
|
|
|
Refer to API objects without saying "object," unless omitting "object"
|
|
|
|
|
leads to an awkward construction.
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Do</th><th>Don't</th></tr>
|
|
|
|
|
<tr><td>The Pod has two containers.</td><td>The pod has two containers.</td></tr>
|
|
|
|
|
<tr><td>The Deployment is responsible for ...</td><td>The Deployment object is responsible for ...</td></tr>
|
|
|
|
|
<tr><td>A PodList is a list of Pods.</td><td>A Pod List is a list of pods.</td></tr>
|
|
|
|
|
<tr><td>The two ContainerPorts ...</td><td>The two ContainerPort objects ...</td></tr>
|
|
|
|
|
<tr><td>The two ContainerStateTerminated objects ...</td><td>The two ContainerStateTerminateds ...</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
{{< table caption = "Do and Don't - API objects" >}}
|
|
|
|
|
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 ...
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Use angle brackets for placeholders
|
|
|
|
|
|
|
|
|
@@ -77,36 +79,40 @@ represents.
|
|
|
|
|
|
|
|
|
|
### Use bold for user interface elements
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Do</th><th>Don't</th></tr>
|
|
|
|
|
<tr><td>Click <b>Fork</b>.</td><td>Click "Fork".</td></tr>
|
|
|
|
|
<tr><td>Select <b>Other</b>.</td><td>Select 'Other'.</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
{{< table caption = "Do and Don't - Bold interface elements" >}}
|
|
|
|
|
Do | Don't
|
|
|
|
|
:--| :-----
|
|
|
|
|
Click **Fork**. | Click "Fork".
|
|
|
|
|
Select **Other**. | Select "Other".
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
|
|
|
|
|
### Use italics to define or introduce new terms
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Do</th><th>Don't</th></tr>
|
|
|
|
|
<tr><td>A <i>cluster</i> is a set of nodes ...</td><td>A "cluster" is a set of nodes ...</td></tr>
|
|
|
|
|
<tr><td>These components form the <i>control plane.</i></td><td>These components form the <b>control plane.</b></td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
{{< table caption = "Do and Don't - Use italics for new terms" >}}
|
|
|
|
|
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**.
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
|
|
|
|
|
### Use code style for filenames, directories, and paths
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Do</th><th>Don't</th></tr>
|
|
|
|
|
<tr><td>Open the <code>envars.yaml</code> file.</td><td>Open the envars.yaml file.</td></tr>
|
|
|
|
|
<tr><td>Go to the <code>/docs/tutorials</code> directory.</td><td>Go to the /docs/tutorials directory.</td></tr>
|
|
|
|
|
<tr><td>Open the <code>/_data/concepts.yaml</code><!--to-unbreak-atom-highlighting_--> file.</td><td>Open the /_data/concepts.yaml<!--to-unbreak-atom-highlighting_--> file.</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
{{< table caption = "Do and Don't - Use code style for filenames, directories, and paths" >}}
|
|
|
|
|
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.
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
|
|
|
|
|
### Use the international standard for punctuation inside quotes
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Do</th><th>Don't</th></tr>
|
|
|
|
|
<tr><td>events are recorded with an associated "stage".</td><td>events are recorded with an associated "stage."</td></tr>
|
|
|
|
|
<tr><td>The copy is called a "fork".</td><td>The copy is called a "fork."</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
{{< table caption = "Do and Don't - Use the international standard for punctuation inside quotes" >}}
|
|
|
|
|
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."
|
|
|
|
|
{{< /table >}}
|
|
|
|
|
|
|
|
|
|
## Inline code formatting
|
|
|
|
|
|
|
|
|
@@ -115,13 +121,17 @@ represents.
|
|
|
|
|
For inline code in an HTML document, use the `<code>` tag. In a Markdown
|
|
|
|
|
document, use the backtick (`).
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Do</th><th>Don't</th></tr>
|
|
|
|
|
<tr><td>The <code>kubectl run</code> command creates a Deployment.</td><td>The "kubectl run" command creates a Deployment.</td></tr>
|
|
|
|
|
<tr><td>For declarative management, use <code>kubectl apply</code>.</td><td>For declarative management, use "kubectl apply".</td></tr>
|
|
|
|
|
<tr><td>Enclose code samples with triple backticks. <code>(```)</code></td><td>Enclose code samples with any other syntax.</td></tr>
|
|
|
|
|
<tr><td>Use single backticks to enclose inline code. For example, `var example = true`.</td><td>Use two asterisks (**) or an underscore (_) to enclose inline code. For example, **var example = true**.</td></tr><tr><td>Use triple backticks before and after a multi-line block of code for fenced code blocks.</td><td>Use multi-line blocks of code to create diagrams, flowcharts, or other illustrations.</td></tr><tr><td>Use meaningful variable names that have a context.</td><td>Use variable names such as 'foo','bar', and 'baz' that are not meaningful and lack context.</td></tr><tr><td>Remove trailing spaces in the code.</td><td>Add trailing spaces in the code, where these are important, because the screen reader will read out the spaces as well.</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
{{< 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
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Do</th><th>Don't</th></tr>
|
|
|
|
|
<tr><td>Set the value of the <code>replicas</code> field in the configuration file.</td><td>Set the value of the "replicas" field in the configuration file.</td></tr>
|
|
|
|
|
<tr><td>The value of the <code>exec</code> field is an ExecAction object.</td><td>The value of the "exec" field is an ExecAction object.</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
{{< 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.
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Do</th><th>Don't</th></tr>
|
|
|
|
|
<tr><td>Set the value of <code>imagePullPolicy</code> to Always.</td><td>Set the value of <code>imagePullPolicy</code> to "Always".</td></tr>
|
|
|
|
|
<tr><td>Set the value of <code>image</code> to nginx:1.8.</td><td>Set the value of <code>image</code> to <code>nginx:1.8</code>.</td></tr>
|
|
|
|
|
<tr><td>Set the value of the <code>replicas</code> field to 2.</td><td>Set the value of the <code>replicas</code> field to <code>2</code>.</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
{{< 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
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Do</th><th>Don't</th></tr>
|
|
|
|
|
<tr><td>kubectl get pods</td><td>$ kubectl get pods</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
{{< 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.
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Term</th><th>Usage</th></tr>
|
|
|
|
|
<tr><td>Kubernetes</td><td>Kubernetes should always be capitalized.</td></tr>
|
|
|
|
|
<tr><td>Docker</td><td>Docker should always be capitalized.</td></tr>
|
|
|
|
|
<tr><td>SIG Docs</td><td>SIG Docs rather than SIG-DOCS or other variations.</td></tr>
|
|
|
|
|
<tr><td>On-premises</td><td>On-premises or On-prem rather than On-premise or other variations.</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
{{< 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.
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Do</th><th>Don't</th></tr>
|
|
|
|
|
<tr><td>Update the title in the front matter of the page or blog post.</td><td>Use first level heading, as Hugo automatically converts the title in the front matter of the page into a first-level heading.</td></tr><tr><td>Use ordered headings to provide a meaningful high-level outline of your content.</td><td>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.</td>
|
|
|
|
|
<tr><td>Use pound or hash signs (#) for non-blog post content.</td><td> Use underlines (--- or ===) to designate first-level headings.</td></tr>
|
|
|
|
|
<tr><td>Use sentence case for headings. For example, <b>Extend kubectl with plugins</b></td><td>Use title case for headings. For example, <b>Extend Kubectl With Plugins</b></td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
{{< 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
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Do</th><th>Don't</th></tr>
|
|
|
|
|
<tr><td>Try to keep paragraphs under 6 sentences.</td><td>Indent the first paragraph with space characters. For example, ⋅⋅⋅Three spaces before a paragraph will indent it.</td></tr>
|
|
|
|
|
<tr><td>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.</td><td>Use horizontal rules for decoration.</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
{{< 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
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Do</th><th>Don't</th></tr>
|
|
|
|
|
<tr><td>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.</td><td>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.</td></tr> <tr><td>Write Markdown-style links ([link text](URL)). For example, <code>[Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/#table-captions)</code> and the output is <a href="/docs/contribute/style/hugo-shortcodes/#table-captions">Hugo shortcodes.</td><td>Write HTML-style links <code>(<link href="/media/examples/link-element-example.css" target="_blank">Visit our tutorial!)</code> or create links that open in new tabs or windows. For example, <code>[example website](https://example.com){target="_blank"}</code></td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
{{< 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 <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 >}}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 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
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Do</th><th>Don't</th></tr>
|
|
|
|
|
<tr><td>This command starts a proxy.</td><td>This command will start a proxy.</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
{{< 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
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Do</th><th>Don't</th></tr>
|
|
|
|
|
<tr><td>You can explore the API using a browser.</td><td>The API can be explored using a browser.</td></tr>
|
|
|
|
|
<tr><td>The YAML file specifies the replica count.</td><td>The replica count is specified in the YAML file.</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
{{< 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."
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Do</th><th>Don't</th></tr>
|
|
|
|
|
<tr><td>To create a ReplicaSet, ...</td><td>In order to create a ReplicaSet, ...</td></tr>
|
|
|
|
|
<tr><td>See the configuration file.</td><td>Please see the configuration file.</td></tr>
|
|
|
|
|
<tr><td>View the Pods.</td><td>With this next command, we'll view the Pods.</td></tr>
|
|
|
|
|
|
|
|
|
|
</table>
|
|
|
|
|
{{< 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"
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Do</th><th>Don't</th></tr>
|
|
|
|
|
<tr><td>You can create a Deployment by ...</td><td>We'll create a Deployment by ...</td></tr>
|
|
|
|
|
<tr><td>In the preceding output, you can see...</td><td>In the preceding output, we can see ...</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
{{< 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.
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Do</th><th>Don't</th></tr>
|
|
|
|
|
<tr><td>For example, ...</td><td>e.g., ...</td></tr>
|
|
|
|
|
<tr><td>That is, ...</td><td>i.e., ...</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
{{< 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.
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Do</th><th>Don't</th></tr>
|
|
|
|
|
<tr><td>Version 1.4 includes ...</td><td>In version 1.4, we have added ...</td></tr>
|
|
|
|
|
<tr><td>Kubernetes provides a new feature for ...</td><td>We provide a new feature ...</td></tr>
|
|
|
|
|
<tr><td>This page teaches you how to use Pods.</td><td>In this page, we are going to learn about Pods.</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
{{< 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.
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Do</th><th>Don't</th></tr>
|
|
|
|
|
<tr><td>Internally, ...</td><td>Under the hood, ...</td></tr>
|
|
|
|
|
<tr><td>Create a new cluster.</td><td>Turn up a new cluster.</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
{{< 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.
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<tr><th>Do</th><th>Don't</th></tr>
|
|
|
|
|
<tr><td>In version 1.4, ...</td><td>In the current version, ...</td></tr>
|
|
|
|
|
<tr><td>The Federation feature provides ...</td><td>The new Federation feature provides ...</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
{{< 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 %}}
|
|
|
|
|
|
|
|
|
|
Tunde Oladipupo