update style guide
Karen Bradshaw
parent
b9f9f71889
commit
e13661c5fe
|
|
@ -17,8 +17,6 @@ Changes to the style guide are made by SIG Docs as a group. To propose a change
|
|||
or addition, [add it to the agenda](https://docs.google.com/document/d/1ddHwLK3kUMX1wVFIwlksjTk0MsqitBnWPe1LRa1Rx5A/edit) for an upcoming SIG Docs meeting, and attend the meeting to participate in the
|
||||
discussion.
|
||||
|
||||
|
||||
|
||||
<!-- body -->
|
||||
|
||||
{{< note >}}
|
||||
|
|
@ -48,12 +46,11 @@ When you refer specifically to interacting with an API object, use [UpperCamelCa
|
|||
|
||||
When you are generally discussing an API object, use [sentence-style capitalization](https://docs.microsoft.com/en-us/style-guide/text-formatting/using-type/use-sentence-style-capitalization).
|
||||
|
||||
You may use the word "resource", "API", or "object" to clarify a Kubernetes resource type in a sentence.
|
||||
You may use the word "resource", "API", or "object" to clarify a Kubernetes resource type in a sentence.
|
||||
|
||||
Don't split the API object name into separate words. For example, use
|
||||
PodTemplateList, not Pod Template List.
|
||||
Don't split an API object name into separate words. For example, use PodTemplateList, not Pod Template List.
|
||||
|
||||
The following examples focus on capitalization. Review the related guidance on [Code Style](#code-style-inline-code) for more information on formatting API objects.
|
||||
The following examples focus on capitalization. For more information about formatting API object names, review the related guidance on [Code Style](#code-style-inline-code).
|
||||
|
||||
{{< table caption = "Do and Don't - Use Pascal case for API objects" >}}
|
||||
Do | Don't
|
||||
|
|
@ -65,17 +62,18 @@ Every ConfigMap object is part of a namespace. | Every configMap object is part
|
|||
For managing confidential data, consider using the Secret API. | For managing confidential data, consider using the secret API.
|
||||
{{< /table >}}
|
||||
|
||||
|
||||
### Use angle brackets for placeholders
|
||||
|
||||
Use angle brackets for placeholders. Tell the reader what a placeholder
|
||||
represents.
|
||||
represents, for example:
|
||||
|
||||
1. Display information about a pod:
|
||||
Display information about a pod:
|
||||
|
||||
kubectl describe pod <pod-name> -n <namespace>
|
||||
```shell
|
||||
kubectl describe pod <pod-name> -n <namespace>
|
||||
```
|
||||
|
||||
If the namespace of the pod is `default`, you can omit the '-n' parameter.
|
||||
If the namespace of the pod is `default`, you can omit the '-n' parameter.
|
||||
|
||||
### Use bold for user interface elements
|
||||
|
||||
|
|
@ -189,7 +187,6 @@ Set the value of `image` to nginx:1.16. | Set the value of `image` to `nginx:1.1
|
|||
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
|
||||
|
|
@ -200,17 +197,20 @@ Do | Don't
|
|||
kubectl get pods | $ kubectl get pods
|
||||
{{< /table >}}
|
||||
|
||||
|
||||
### Separate commands from output
|
||||
|
||||
Verify that the pod is running on your chosen node:
|
||||
|
||||
kubectl get pods --output=wide
|
||||
```shell
|
||||
kubectl get pods --output=wide
|
||||
```
|
||||
|
||||
The output is similar to this:
|
||||
|
||||
NAME READY STATUS RESTARTS AGE IP NODE
|
||||
nginx 1/1 Running 0 13s 10.200.0.4 worker0
|
||||
```console
|
||||
NAME READY STATUS RESTARTS AGE IP NODE
|
||||
nginx 1/1 Running 0 13s 10.200.0.4 worker0
|
||||
```
|
||||
|
||||
### Versioning Kubernetes examples
|
||||
|
||||
|
|
@ -263,17 +263,17 @@ Hugo [Shortcodes](https://gohugo.io/content-management/shortcodes) help create d
|
|||
|
||||
2. Use the following syntax to apply a style:
|
||||
|
||||
```
|
||||
{{</* note */>}}
|
||||
No need to include a prefix; the shortcode automatically provides one. (Note:, Caution:, etc.)
|
||||
{{</* /note */>}}
|
||||
```
|
||||
```none
|
||||
{{</* note */>}}
|
||||
No need to include a prefix; the shortcode automatically provides one. (Note:, Caution:, etc.)
|
||||
{{</* /note */>}}
|
||||
```
|
||||
|
||||
The output is:
|
||||
The output is:
|
||||
|
||||
{{< note >}}
|
||||
The prefix you choose is the same text for the tag.
|
||||
{{< /note >}}
|
||||
{{< note >}}
|
||||
The prefix you choose is the same text for the tag.
|
||||
{{< /note >}}
|
||||
|
||||
### Note
|
||||
|
||||
|
|
@ -403,7 +403,7 @@ The output is:
|
|||
|
||||
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.
|
||||
|
||||
|
|
@ -417,13 +417,14 @@ Shortcodes inside include statements will break the build. You must insert them
|
|||
{{</* /note */>}}
|
||||
```
|
||||
|
||||
|
||||
## Markdown elements
|
||||
|
||||
### Line breaks
|
||||
|
||||
Use a single newline to separate block-level content like headings, lists, images, code blocks, and others. The exception is second-level headings, where it should be two newlines. Second-level headings follow the first-level (or the title) without any preceding paragraphs or texts. A two line spacing helps visualize the overall structure of content in a code editor better.
|
||||
|
||||
### 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 caption = "Do and Don't - Headings" >}}
|
||||
|
|
@ -453,24 +454,24 @@ Write hyperlinks that give you context for the content they link to. For example
|
|||
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.
|
||||
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.
|
||||
- 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 >}}
|
||||
{{< 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 the number one (`1.`) for ordered lists.
|
||||
|
||||
- Use (`+`), (`*`), or (`-`) for unordered lists.
|
||||
- Use (`+`), (`*`), or (`-`) for unordered lists.
|
||||
|
||||
- Leave a blank line after each list.
|
||||
- Leave a blank line after each list.
|
||||
|
||||
- Indent nested lists with four spaces (for example, ⋅⋅⋅⋅).
|
||||
- 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.
|
||||
- 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
|
||||
|
||||
|
|
@ -490,7 +491,6 @@ 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.
|
||||
|
||||
|
|
@ -503,7 +503,6 @@ You can explore the API using a browser. | The API can be explored using a brows
|
|||
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.
|
||||
|
||||
### Use simple and direct language
|
||||
|
|
@ -527,7 +526,6 @@ 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.
|
||||
|
|
@ -539,7 +537,6 @@ For example, ... | e.g., ...
|
|||
That is, ...| i.e., ...
|
||||
{{< /table >}}
|
||||
|
||||
|
||||
Exception: Use "etc." for et cetera.
|
||||
|
||||
## Patterns to avoid
|
||||
|
|
@ -557,7 +554,6 @@ 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.
|
||||
|
|
@ -569,7 +565,6 @@ Internally, ... | Under the hood, ...
|
|||
Create a new cluster. | Turn up a new cluster.
|
||||
{{< /table >}}
|
||||
|
||||
|
||||
### Avoid statements about the future
|
||||
|
||||
Avoid making promises or giving hints about the future. If you need to talk about
|
||||
|
|
@ -588,6 +583,18 @@ In version 1.4, ... | In the current version, ...
|
|||
The Federation feature provides ... | The new Federation feature provides ...
|
||||
{{< /table >}}
|
||||
|
||||
### Avoid words that assume a specific level of understanding
|
||||
|
||||
Avoid words such as "just", "simply", "easy", "easily", or "simple". These words do not add value.
|
||||
|
||||
{{< table caption = "Do and Don't - Avoid insensitive words" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
Include one command in ... | Include just one command in ...
|
||||
Run the container ... | Simply run the container ...
|
||||
You can easily remove ... | You can remove ...
|
||||
These simple steps ... | These steps ...
|
||||
{{< /table >}}
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue