Kubernetes docs style guidelines - capitalization

[Andrea Hoffer]

Hi everyone,

We’re evaluating the way that we capitalize and present Kubernetes terms throughout our Red Hat OpenShift documentation. We've currently been trying to follow the Kubernetes style guidance of capitalizing API objects [1]; for example, capitalizing all instances of “Pod” and “Deployment”. 

However, we have a few concerns with this:

• We follow the IBM style guide, which would recommend to use lowercase for the terms in general usage.
• We notice that some terms seem to be exempt from this guidance (node, namespace, etc.), which makes the guidance hard to follow.
• We notice that even in the Kubernetes docs, the term capitalization can be inconsistent.
• We often get questions from stakeholders and contributors asking why we’re capitalizing these terms or asking us to lowercase them.
  

As a writing team, we tend to believe that general use of these terms should be lowercase. But we would also prefer to follow the Kubernetes style guidelines if possible, which is why we’re reaching out. 

We’d like to understand the reasons behind the guidance:

• What is the reason behind the guidance to capitalize all instances of terms that are an API object?
• Why is the guidance not applicable to image, node, namespace, etc.? Not that we want to start capitalizing these, but we want to understand why the guidance does not apply to some terms.
• There is a section of the style guide [2] that says to use general descriptors over component names, so we were wondering whether something similar could apply to the API object guidance as well.

Any thoughts on this are appreciated.

Thanks!

Andrea

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

[2] https://kubernetes.io/docs/contribute/style/style-guide/#use-a-general-descriptor-over-a-component-name

[Qiming Teng]

Here are some of my understandings.

One of the rules we strive to follow is to use camel cases for API objects. For example, we use "Deployment" when we are referring to the "v1/Deployment" resource type or its object, so readers get a better idea what we meant to say. Similarly, we use 'Container' when we refer to the "v1/Container", etc. With this guideline, we hope we can avoid confusing readers when we say 'Role', 'Status', 'Event', 'Node'.

However, when we are discussing the status of an object, we do not always say 'Status', because the context is very clear. We still use 'Status' when we want to emphasize that we are referring to the API object named "Status".

As for the guideline about "general descriptor" over component names, one of the reasons behind that is for consistency. We saw different authors using "kube-apiserver", "apiserver", "Apiserver" and we wanted these to be consistent and converge to a generic term, i.e. "API server".

There are many places where improvements are needed for consistency and accuracy. However, the Kubernetes website contents are contributed by authors with different background, and we are short of hands on making everything perfect. For example, when discussing the `spec` field of a Pod, we may still see "PodSpec" is used when we should use `spec`. When we are referring to the API Definition of "PodSpec", we are not spelling the word correctly. When we discuss the DNS policy for a Pod, we see both "DNSPolicy" and "dnsPolicy" where the former is the API definition name and the latter is the user facing field name.

Regards,

  Qiming

[Andrea Hoffer]

Hi Qiming,

Thanks a lot for the response.

One of the rules we strive to follow is to use camel cases for API objects.

I do see the guidance on using PascalCase for all terms that are API objects, but am wondering exactly what the reason for that decision was. Did you find that readers were confused if you didn’t? And then also wondering why this guidance was not applied to every single term that is also an API object. So if there are exceptions to this rule, it would be good to know what they are, and why they have been given an exception. If you look through the glossary page [1], you can see quite a few instances of terms that are technically API objects, but do not follow the guidance. As an example, the glossary lists "Pod Disruption Budget". If you were trying to follow the always PascalCase guidance, it should be "PodDisruptionBudget". Even though I would prefer to see the words lowercase, this gives a good example of how you can still understand the term without needing to present it as an object in every usage.

Similarly, we use 'Container' when we refer to the "v1/Container", etc. With this guideline, we hope we can avoid confusing readers when we say 'Role', 'Status', 'Event', 'Node'.

You mentioned “Node” in your example, but in the Kubernetes docs, I see "node" frequently lowercase. You can see that even a page like this [2] goes back and forth between capitalization, which looks like it might be trying to only capitalize for the actual object reference. Even in the glossary, the description for "Node" uses lowercase.

However, when we are discussing the status of an object, we do not always say 'Status', because the context is very clear.

The logic that you use for the status example is exactly the logic that we’re thinking could be applied across the board. In the context of Kubernetes documentation, it should be clear what a pod is, or what an event is, without having to capitalize each instance.

So what we think should be considered is to lowercase terms when you are just discussing them generally. But then you can use PascalCase when you are specifically referring to interacting with the API object. And in these cases, the API object should probably be in monospace to be clearer as to why there is a switch in capitalization. I think that the page on nodes that I linked earlier would probably read more nicely if all instances of "Node" were in monospace like a field or a flag.

Happy to hear thoughts on this.

Thanks!

Andrea

[1] https://kubernetes.io/docs/reference/glossary/?all=true

[2] https://kubernetes.io/docs/concepts/architecture/nodes/

--
You received this message because you are subscribed to the Google Groups "kubernetes-sig-docs" group.
To unsubscribe from this group and stop receiving emails from it, send an email to kubernetes-sig-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/kubernetes-sig-docs/a93a6d5e-cf05-42e0-846a-ab998f1fd0c4n%40googlegroups.com.

--

Andrea Hoffer

Technical Writer

Customer CONTENT SERVICES

red hat, inc.

[Cassandra Oxford]

Hi,

I usually just lurk on this SIG board, but felt the need to second Andrea's suggestion in this case:

So what we think should be considered is to lowercase terms when you are just discussing them generally. But then you can use PascalCase when you are specifically referring to interacting with the API object. And in these cases, the API object should probably be in monospace to be clearer as to why there is a switch in capitalization. I think that the page on nodes that I linked earlier would probably read more nicely if all instances of "Node" were in monospace like a field or a flag.

We have recently been discussing how to implement the same guidance on our docs team here (specifically around Pods).  

Casie Oxford

D2IQ, Inc.

Documentation Manager

To view this discussion on the web visit https://groups.google.com/d/msgid/kubernetes-sig-docs/CAAHNXPLfbM55xuMCG0oLzn5AE3Chbm8aLNVL_dZm17C5%3DBO7oA%40mail.gmail.com.

[zcorl...@linuxfoundation.org]

Hi Andrea,

> I do see the guidance on using PascalCase for all terms that are API objects, but am wondering exactly what the reason for that decision was. Did you find that readers were confused if you didn’t? 

Yes. 

> And then also wondering why this guidance was not applied to every single term that is also an API object. 

We're a massive open source project with a severely understaffed number of technical writers and reviewers with multiple competing priorities. The fix for issues like this is for upstream companies to hire more technical writers dedicated to upstream work.

In most of your questions and observations below, I refer back frequently to the previous two sentences.

> So if there are exceptions to this rule, it would be good to know what they are, and why they have been given an exception. 

Please see above.

> If you look through the glossary page [1], you can see quite a few instances of terms that are technically API objects, but do not follow the guidance. 

Please see above.

> You can see that even a page like this [2] goes back and forth between capitalization, which looks like it might be trying to only capitalize for the actual object reference. 

Hopefully, yes, given that's the guidance I think we were trying to achieve. I agree that the style guide isn't clear and needs to be.

> Even in the glossary, the description for "Node" uses lowercase.

Please see above.

> In the context of Kubernetes documentation, it should be clear what a pod is, or what an event is, without having to capitalize each instance.

Except when it refers to the API object, as opposed to an instance of that object.

> So what we think should be considered is to lowercase terms when you are just discussing them generally. 

That seems reasonable. Who will apply this change across the docs?

> And in these cases, the API object should probably be in monospace to be clearer as to why there is a switch in capitalization. 

Please feel free to open an issue and a PR suggesting that change.

> I think that the page on nodes that I linked earlier would probably read more nicely if all instances of "Node" were in monospace like a field or a flag.

Please feel free to open a Pull Request with the proposed changes.

Thanks,

Zach

[zcorl...@linuxfoundation.org]

Hi Casie,

Please feel free to open an issue and a Pull Request making the specific changes.

Thanks,

Zach

[William Abernathy]

As some of you know, I've been having a protracted dialogue concerning this topic at: https://github.com/kubernetes/website/issues/20862

While I don't believe I've gotten to a completely satisfactory solution to this, I do feel I have a better understanding than when I started. Fundamental problems are terminological (a loose definition of camel case vs. Pascal case in the style guide, for instance) and the somewhat fluid usage of the terms "object," "resource," and "API." Likewise, I consider some of the directives to writers on this topic to have been ill-considered. Bottom line: people should capitalize proper nouns, but the Kubernetes style guide actively discourages written cues indicating a noun is proper. From the perspective of a non-programming technical writer, I find myself in a circular definition: Capitalize "pod" when it refers to a resource/object/API, which distinction is only discernible by checking the capitalization.

I've cooked up the following for my house style guide. I hope you find it useful. If not, feel free to help me make it moreso. I approach our solution similarly to Casie, but I prefer to let words, rather than typesetting, do the heavy lifting (our house style used entirely too much monospace, and we are in the "possibly overcorrecting" phase of setting things to right).

--------------------

Kubernetes API Names and References

Kubernetes API names are set in PascalCase (see: https://kubernetes.io/docs/contribute/style/style-guide/#use-camel-case-for-api-objects. Yes, it says “camel case” but it shows Pascal case). The Kubernetes style guide explicitly rejects following Pascal-cased words with the resource’s type, such as “object,” “resource,” or “API”. We reject this, because several single-word named APIs use the Pascal case (FooBar) style, making it impossible to discern without context whether the word is capitalized correctly (as a proper name for a Pascal-cased API, object, or resource).

The following words may be correctly set in Pascal case:

• Binding

• Container

• Deployment

• Endpoints

• Event

• Ingress

• Job

• Lease

• Namespace

• Node

• Pod

• Role

• Secret

• Service

• Volume

This list of names is not magic: capitalize these only when they are proper nouns (names of APIs). When setting a single-word (Pascal case) API from this list, identify it as such the first time you use it in a narrative description. For example, “The PodList resource contains a list of Pod APIs…” If it is set thus, Tech Pubs is much less likely to request clarification. Avoid pluralizing the proper name in favor of pluralizing its referent. For example, “The SecretList contains one or more Secret objects,” not “The SecretList contains one or more Secrets.”

--------------------

Thanks to Max Bridges for alerting me to this discussion, and to anyone with the fortitude to have made it this far!

--William

On Wednesday, August 26, 2020 at 2:21:58 PM UTC-7 cox...@d2iq.com wrote:

[zcorl...@linuxfoundation.org]

Hi William,

> Likewise, I consider some of the directives to writers on this topic to have been ill-considered.

Sorry to hear that. Please see my reply to Andrea about understaffing and upstream hiring mandates.

> I've cooked up the following for my house style guide. I hope you find it useful. If not, feel free to help me make it moreso.

Please feel free to open a Pull Request to improve the existing style guide.

Thanks,

Zach

[zcorl...@linuxfoundation.org]

Folks,

I'm happy to see so much interest in the style guide and about best practices for capitalization. Robust discussion makes for vibrant communities.

SIG Docs prioritizes changes based on the needs of our readers. So far, prose capitalization hasn't emerged as a significant source of friction for developers and cluster admins.

Speaking frankly as a SIG leader, I'm not willing to burn community energy on hypotheticals or "shoulds", nor to pursue unfunded mandates. Like many communities, Kubernetes runs on participation and trust earned over time. There are plenty of opportunities to participate in Kubernetes docs as reviewers and contributors, and eventually as approvers, tech leads, and chairs.

Kubernetes docs happen through contribution, not through the mere presence of strong opinions. If you want to see changes, the best advice I can give is to start attending meetings and opening Pull Requests. Issues like https://github.com/kubernetes/website/issues/20862 may make for interesting discussions, but they don't speak as loudly as a willingness to put in the work. 

For more information, see https://kubernetes.io/docs/contribute/.

All the best,

Zach

[Cassandra Oxford]

Absolutely true. Probably the first place to start to help would be the style guide. I'll see if I can open a PR for that first. 

Casie 

To view this discussion on the web visit https://groups.google.com/d/msgid/kubernetes-sig-docs/11a546a6-67bc-48cb-b2fb-951dad4203b7n%40googlegroups.com.

--

Casie Oxford

D2IQ, Inc.

Documentation Manager

Mobile: 972-977-2871

[zcorl...@linuxfoundation.org]

Glad to see this PR, Casie! https://github.com/kubernetes/website/pull/23497

Some helpful tips for folks signing the CLA:

- Sign the CLA with the same email attached to your GitHub user ID.

- Make GitHub commits with the user ID and email signed to the CLA.

Thanks,

Zach