Website: Recommend change to use code styling for API objects

[cmastr]

This is a Bug Report

Problem:

The style guide needs clearer guidance for casing and styling API Objects.

This standard aligns with GitHub's and Google's API conventions.

Proposed Solution:

• Case API Objects in single spaced upper camel case (UpperCamelCase)
• Style API Objects with a monospace font

For example: HorizontalPodAutoscaler

Page to Update:

https://kubernetes.io/docs/contribute/style/style-guide/#inline-code-formatting

Additional Information: PR started here:

23497

[sftim]

Hi @cmastr

Can you expand a bit on the style guide change you have in mind? It might be that you want to suggest replacing, eg:

Now type kubectl get configmap --all-namespaces

with

Now type kubectl get ConfigMap --all-namespaces

Possibly though you wanted to revise the (misleading?) advice to write API object types in CamelCase: https://kubernetes.io/docs/contribute/style/style-guide/#use-camel-case-for-api-objects
(camel case is usually writtenLikeThis, and the case used for API objects in Kubernetes is called PascalCase or sometimes UpperCamelCase).

[sftim]

See https://deploy-preview-23767--kubernetes-io-master-staging.netlify.app/docs/concepts/architecture/nodes/ for an example (from PR #23767) of using monospaced, gray-background PascalCase for object types.

[zacharysarah]

@cmastr 👍 to @sftim's feedback. I would change this issue's description to something like:

Problem:

The style guide needs clearer guidance for casing and styling API Objects.

Proposed Solution:

- Case API Objects in single spaced upper camel case (UpperCamelCase)
- Style API Objects with a monospace font

For example: `HorizontalPodAutoscaler`

This standard aligns with GitHub's and Google's API conventions.

[cmastr]

@cmastr 👍 to @sftim's feedback. I would change this issue's description to something like:

Problem:

The style guide needs clearer guidance for casing and styling API Objects.

Proposed Solution:

- Case API Objects in single spaced upper camel case (UpperCamelCase)
- Style API Objects with a monospace font

For example: `HorizontalPodAutoscaler`

This standard aligns with GitHub's and Google's API conventions.

Ok this is done.

[sftim]

At the moment, there is a difference in rendering between

1. how names you use on the command line with kubectl (eg kubectl get Deployment) appear (currently: UpperCamelCase, not monospace)
2. how the details you see in a manifest appear (eg .metadata.name) appear (currently: lowerCamelCase, monospace)

Is there a way to preserve the difference to that it's clear to readers who know the convention _and_ still help people who are newer to the Kubernetes documentation understand that terms like Secret and Deployment are more than just the English words they're based on?

(Possibly the answer is to use shortcodes somewhere. Possibly.)

[bergerhoffer]

Hi @sftim - before continuing, I assume that resource types passed to kubectl are case insensitive. Is that a correct assumption?

I hadn't been considering kubectl commands in this guidance at all. The guidance change was more targeted for referring to terms/objects in normal running text (as per the examples here [1]). I had just assumed that the resource names in kubectl commands were always lowercase. Like when you do --help on a particular kubectl command, the examples I see show in lowercase. (kubectl get pods, etc.).

And what I see in the Kubernetes docs normally does this as well, for example: https://kubernetes.io/docs/tasks/access-application-cluster/service-access-application-cluster/#creating-a-service-for-an-application-running-in-two-pods

If I were writing your example command, I would write kubectl get deployment, where the entire command is in monospace. Are you suggesting that "deployment" in this case should be PascalCase "Deployment" if following the existing guidelines? Or interpreting that this proposal is suggesting that (it shouldn't be)? Thanks!

[1] https://kubernetes.io/docs/contribute/style/style-guide/#use-camel-case-for-api-objects

[sftim]

I assume that resource types passed to kubectl are case insensitive. Is that a correct assumption?

Yep

When we illustrate these commands with shell snippets, we write resource names lower case. I think that's fine because the CLI also prints those resource names lowercase (to try this: kubectl get Namespace -o name). Let's make sure the style guide ends up clear on this aspect too.

Overall: most of the time, the documentation is matching the capitalization that the code and tools already use.

I suppose that .metadata.name also appears on the command line. Anyway, by “resources” I mean “things you can kubectl get”.

[sftim]

Some differences:

kubectl get namespace kube-system # works
kubectl get nAmEsPaCe kube-system # works
kubectl get namespace kube-system -o go-template='{{ .metadata.name }}' # works
kubectl get namespace kube-system -o go-template='{{ .metaData.name }}' # no value

[kbhawkey]

Hello.
Re: This standard aligns with GitHub's and Google's API conventions.

I'd like more feedback about using monospace for the
resource names in the content (not code blocks) before changing the way the site formats
resources. For me, matching the exact spelling and case of the resource to the
type definition in Go (and in the reference guide, data samples), identifies the resource.
The font does not matter.
In the content, the resources appear in paragraphs describing what happens when something does xxxxx.
The sentences tend to be longer than shorter.
The documentation typically does not show or describe Go code in detail. The API reference provides this detail.
When the resources appear as data (in configuration or manifests), then all the fields are treated as a code block.

It would be very helpful for me if someone could provide the specific URLs to the Github and Google
style guides that show the rules you are suggesting. I noted that the Google developer style guide
has flexible rules for the Kubernetes terms.
Thanks!

[kbhawkey]

Here are some typical constructs in the content:
You can create and modify Node objects using kubectl .
You can create and modify Node resources using kubectl .
[possibly used?] You can create and modify Nodes using kubectl .
You can create and modify ServiceAccounts using kubectl .
[not used] You can create and modify nodes using kubectl.

Node/node , Service/service, Deployment/deployment, Container/container, and now Pod/pod are overloaded terms.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale