update style guide for styling component names #17588

kbhawkey · 2019-11-14T21:41:36Z

There are a number of ways that the Kubernetes components are named and styled. It would be helpful to standardize (or reach consensus) on how to style and name the components.
This PR is an attempt to outline style conventions for components and component tools.

netlify · 2019-11-14T21:50:27Z

Deploy preview for kubernetes-io-master-staging ready!

Built with commit 040b1a2

https://deploy-preview-17588--kubernetes-io-master-staging.netlify.com

tengqm · 2019-11-18T01:41:40Z

content/en/docs/contribute/style/style-guide.md

+:--| :-----
+The `kubelet` preserves node stability. | The kubelet preserves node stability.
+The `kube-proxy` maintains network rules on nodes. | The kube-proxy maintains network rules on nodes.
+Kubectl handles locating and authenticating to the API server. | `kubectl` handles locating and authenticating to the apiserver.


This example falls into the "Don'ts" category below -- do not start a sentence with a tool name.

@tengqm OK.
There are a number of places in the docs where a cmd/component name starts a sentence. I'll go through the examples on this page again. I am hoping to capture the cases where this may be a possible construction (start the sentence with a capitalized tool/exe name or use something like The kubelet). Do you think cmd tool and component names should use code formatting within a sentence?

I like the idea of using “The ” or similar text to avoid needing to write (eg) “Kube-proxy maintains rules”.

content/en/docs/contribute/style/style-guide.md

sftim · 2019-11-18T14:18:00Z

content/en/docs/contribute/style/style-guide.md

+{{< 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.


Sometimes it seems helpful to use a glossary tooltip so that readers easily know what components are.

I favor writing kubectl in code style, because people type it. Same for other CLI tools. If the option were there, I would write kube-apiserver in monospace but not styled as code.

@sftim, glossary tooltips are helpful, but they can be disruptive if overused on a page.
It is my understanding that using backticks is supposed to render text in monospace.
I can change the component example to use plain text, though, I'd like a different font or font size for k8s component names.

tengqm · 2019-11-19T08:24:39Z

I like this change.
/lgtm

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

- removed code style for components not cmd tools - added style suggestion for namespaces - cleaned up a few stray spaces

tengqm · 2019-11-21T02:13:04Z

/approve

k8s-ci-robot · 2019-11-21T02:13:27Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: tengqm

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~content/en/OWNERS~~ [tengqm]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

Rajakavitha1 · 2019-12-02T10:20:55Z

/lgtm

* 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

* Fix a command in kubectl cheatsheet (kubernetes#17888) * Remove dead links to old getting started guides (kubernetes#17889) * Change PowerShell example to use the -Raw flag (kubernetes#17645) * Spelling correction (kubernetes#17895) * fix some broken links (kubernetes#17897) * update exmaple for job (kubernetes#17903) * Deleted duplicate sentence and corrected typo (kubernetes#17902) * Corrected the typo of 'chck' with 'check' * Removed the duplicate sentence * Fix a dead link (kubernetes#17900) * fix 404 urls in kustomization.md (kubernetes#17793) * Update kustomization.md fix 404 urls in kustomization.md * Update content/en/docs/tasks/manage-kubernetes-objects/kustomization.md Co-Authored-By: Tim Bannister <[email protected]> * update kustomization.md to be more stable * Fix broken link to AWS provider settings source (kubernetes#17899) * update style guide for styling component names (kubernetes#17588) * 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 * fix output example in automated-tasks-with-cron-jobs.md (kubernetes#17906) * Update an out-of-date link (kubernetes#17907) Signed-off-by: umiblue <[email protected]> * en-fr: Append Note To Alternative Linux Install (kubernetes#17827) * Blog post: Gardener Project Update (kubernetes#17516) * Add Gardener Project Update blog post * Update and rename 2019-11-10-gardener-project-update.md to 2019-11-27-gardener-project-update.md * Update and rename 2019-11-27-gardener-project-update.md to 2019-12-02-gardener-project-update.md * Update KubeCon buttons for Shanghai (kubernetes#17916) * fix path not consistent (kubernetes#17923) * updated 3 logos on case studies page (kubernetes#17628) * Update kube-scheduler.md (kubernetes#17283) Fix grammar typo * Add missing `systemctl` step for running `cri-o` (kubernetes#17926) After installing `cri-o`, we must run `systemctl daemon-reload` before trying to run `systemctl start crio`. Otherwise, `systemd` doesn't know about the crio configuration. Similar instructions already exist for installing docker - this diff adds these instructions for crio. * add cidr to glossary (kubernetes#17550) * add CIDR * modify cidr definition * Update content/en/docs/reference/glossary/cidr.md Co-Authored-By: Chris <[email protected]> * Update content/en/docs/reference/glossary/cidr.md Co-Authored-By: Chris <[email protected]> * specify components requiring feature gate (kubernetes#17922) * specify components requiring feature gate currently, TTLafterfinished feature gate is a flag that can be passed to kube-apiserver, kube-scheduler and kube-controller-manager. The current description doesn't state what components to pass the flag to. * specify components requiring feature gate * Fixed hot reload panic of local hugo issue. (kubernetes#17894) * fix-up 404 urls (kubernetes#17936) * fix-up 404 urls * Revert "fix-up 404 urls" This reverts commit 4515c4d. * fix-ip 404 urls * fix-up 404 urls * Update guaranteed-scheduling-critical-addon-pods.md (kubernetes#17151) * Update guaranteed-scheduling-critical-addon-pods.md cleanup old stuff again * Update content/en/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods.md Co-Authored-By: Tim Bannister <[email protected]> * Update guaranteed-scheduling-critical-addon-pods.md remove whitespace * correct diagram label (kubernetes#17942) * fix-up 404 urls (kubernetes#17941) * fix-up 404 urls * Revert "fix-up 404 urls" This reverts commit 4515c4d. * fix-ip 404 urls * fix-up 404 urls * fix-up 404 urls Revert "fix-up 404 urls" This reverts commit 4515c4d. fix-ip 404 urls fix-up 404 urls * fix-up 404 urls * Translate Minikube environment to French (kubernetes#17939) * Freshen the list of English content approvers for SIG Docs (kubernetes#17929) * Add YouTube social button in header and footer (kubernetes#16838) * Update the cluster create and disable commands (kubernetes#17947) * Initialize DNS Pod Service for ID Localization. (kubernetes#16707) Co-Authored-By: Giri Kuncoro <[email protected]> Co-Authored-By: Tim Bannister <[email protected]> * Add statefulsets for ID localization. (kubernetes#16700) * Initialize Common Label for ID Localization. (kubernetes#16706) * Add job running into completion in ID Localization. (kubernetes#16705) * Updated kubeone URL (kubernetes#17766)

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Nov 14, 2019

k8s-ci-robot requested review from Rajakavitha1 and sftim November 14, 2019 21:41

k8s-ci-robot added size/S Denotes a PR that changes 10-29 lines, ignoring generated files. language/en Issues or PRs related to English language sig/docs Categorizes an issue or PR as relevant to SIG Docs. labels Nov 14, 2019

tengqm reviewed Nov 18, 2019

View reviewed changes

content/en/docs/contribute/style/style-guide.md Outdated Show resolved Hide resolved

sftim reviewed Nov 18, 2019

View reviewed changes

kbhawkey force-pushed the update-style-cmd-tool branch from 5096cb3 to f665385 Compare November 18, 2019 14:41

k8s-ci-robot assigned tengqm Nov 19, 2019

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Nov 19, 2019

kbhawkey added 3 commits November 19, 2019 09:56

update style guide for styling component names

152aeba

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

update style examples

0e161de

style edits

040b1a2

- removed code style for components not cmd tools - added style suggestion for namespaces - cleaned up a few stray spaces

kbhawkey force-pushed the update-style-cmd-tool branch from f665385 to 040b1a2 Compare November 19, 2019 15:21

k8s-ci-robot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed lgtm "Looks good to me", indicates that a PR is ready to be merged. size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Nov 19, 2019

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Nov 21, 2019

k8s-ci-robot assigned Rajakavitha1 Dec 2, 2019

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Dec 2, 2019

k8s-ci-robot merged commit 249f88c into kubernetes:master Dec 2, 2019

kbhawkey deleted the update-style-cmd-tool branch July 30, 2020 11:32

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

update style guide for styling component names #17588

update style guide for styling component names #17588

kbhawkey commented Nov 14, 2019

netlify bot commented Nov 14, 2019 •

edited

Loading

tengqm Nov 18, 2019

kbhawkey Nov 18, 2019

sftim Nov 18, 2019

sftim Nov 18, 2019

sftim Nov 18, 2019

kbhawkey Nov 19, 2019

tengqm commented Nov 19, 2019

tengqm commented Nov 21, 2019

k8s-ci-robot commented Nov 21, 2019

Rajakavitha1 commented Dec 2, 2019

update style guide for styling component names #17588

update style guide for styling component names #17588

Conversation

kbhawkey commented Nov 14, 2019

netlify bot commented Nov 14, 2019 • edited Loading

tengqm Nov 18, 2019

Choose a reason for hiding this comment

kbhawkey Nov 18, 2019

Choose a reason for hiding this comment

sftim Nov 18, 2019

Choose a reason for hiding this comment

sftim Nov 18, 2019

Choose a reason for hiding this comment

sftim Nov 18, 2019

Choose a reason for hiding this comment

kbhawkey Nov 19, 2019

Choose a reason for hiding this comment

tengqm commented Nov 19, 2019

tengqm commented Nov 21, 2019

k8s-ci-robot commented Nov 21, 2019

Rajakavitha1 commented Dec 2, 2019

netlify bot commented Nov 14, 2019 •

edited

Loading