diff --git a/content/en/docs/contribute/style/style-guide.md b/content/en/docs/contribute/style/style-guide.md index 5f92636c5f579..30865c49e8ef3 100644 --- a/content/en/docs/contribute/style/style-guide.md +++ b/content/en/docs/contribute/style/style-guide.md @@ -111,7 +111,7 @@ 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." +The copy is called a "fork". | The copy is called a "fork." {{< /table >}} ## Inline code formatting @@ -133,17 +133,46 @@ Use meaningful variable names that have a context. | Use variable names such as 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 >}} +{{< 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) {{< /note >}} -### Use code style for object field names +### Use code style for object field names and namespaces {{< 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. +Run the process as a Daemonset in the `kube-system` namespace. | Run the process as a Daemonset in the kube-system namespace. +{{< /table >}} + +### Use code style for Kubernetes command tool and component names + +{{< table caption = "Do and Don't - Use code style for Kubernetes command tool and component names" >}} +Do | Don't +:--| :----- +The kubelet preserves node stability. | The `kubelet` preserves node stability. +The `kubectl` handles locating and authenticating to the API server. | The kubectl handles locating and authenticating to the apiserver. +Run the process with the certificate, `kube-apiserver --client-ca-file=FILENAME`. | Run the process with the certificate, kube-apiserver --client-ca-file=FILENAME. | +{{< /table >}} + +### Starting a sentence with a component tool or component name + +{{< table caption = "Do and Don't - Starting a sentence with a component tool or component name" >}} +Do | Don't +:--| :----- +The `kubeadm` tool bootstraps and provisions machines in a cluster. | `kubeadm` tool bootstraps and provisions machines in a cluster. +The kube-scheduler is the default scheduler for Kubernetes. | kube-scheduler is the default scheduler for Kubernetes. +{{< /table >}} + +### Use a general descriptor over a component name + +{{< table caption = "Do and Don't - Use a general descriptor over a component name" >}} +Do | Don't +:--| :----- +The Kubernetes API server offers an OpenAPI spec. | The apiserver offers an OpenAPI spec. +Aggregated APIs are subordinate API servers. | Aggregated APIs are subordinate APIServers. {{< /table >}} ### Use normal style for string and integer field values