Skip to content

Commit

Permalink
update style guide for styling component names (kubernetes#17588)
Browse files Browse the repository at this point in the history
* update style guide for styling component names

- Attempt to outline style conventions for components
  and component tools
- Interested in comments and feedback

* update style examples

* style edits

- removed code style for components not cmd tools
- added style suggestion for namespaces
- cleaned up a few stray spaces
  • Loading branch information
kbhawkey authored and zacharysarah committed Dec 5, 2019
1 parent a27a0a3 commit b8f7bd1
Showing 1 changed file with 32 additions and 3 deletions.
35 changes: 32 additions & 3 deletions content/en/docs/contribute/style/style-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down

0 comments on commit b8f7bd1

Please sign in to comment.