Capitalization of Pod, Container, and others

[theletterf]

This is a Feature Request

What would you like to be added

It’d be great if the style guide’s list of words contain key K8s concepts, like Pod and Container, and why they are (more or less consistently) capitalized throughout the docs.

Capitalization rules for K8s objects do not seem to be specified anywhere. If there’s a valid reason for this, it’d be nice to know what that is. It’s a bit frustrating for tech writers not to know when and why capitalization should be applied.

Why is this needed

Consistency throughout the docs.

Comments

We recently discussed this in the Write the Docs community.

[theletterf]

In a passage of @nigelpoulton 's book, there's a hint: Pod, Service, Container, etc. are all objects and API resources, and as such are PascalCase. Could we be explicit about that in the style guide?

[nigelpoulton]

I think capitalising objects adds clarity. A great example is a Kubernetes Service object --- using a capital "S" avoids all confusion.

Also... my inner geek likes this... At school learned that a proper nouns should always be capitalised, and that a proper noun is a person, place or object. Well... in the case of Kubernetes, Pods, Services, Deployments and the likes literally are API objects ;-)

[wabernat]

I thank @theletterf for introducing this here. It was my initial question at WritetheDocs that prompted this, and I hope we can discuss this fruitfully.

@nigelpoulton, I would like to see your book for better context. However, based solely on what I have seen here, I must respectfully disagree with you in every particular.

In this instance, the word "Service" is not a proper noun, nor do the two words (service object) together create a proper noun. In conventional usage, they are not capitalized. To a naïve user, capitalizing "service" here clarifies nothing. Your perception of this usage eliminating confusion is based on A) already understanding and assuming the reader understands the underlying concepts, and B) a fundamental misunderstanding of what a proper noun is.

Unless there is an underlying Anglo-American mistranslation at play here (in which case my apologies in advance), what you describe as a proper noun (a person, place, event, or thing) is simply a noun. A proper noun is a noun that asserts the characteristic of uniqueness. "Kubernetes," for example, is a name that expresses a unique thing, so it is capitalized (the use of the indefinite article "a" here also belies the propriety of the noun).

As I (an ordinary, non-technical reader) read it, a pod is a pod is a pod (lowercase), until it gets a name, at which point we must capitalize it. That a pod is an object or associated in some way with an API no more entitles it to capitalization than to point out that a rock is a literal object or is associated with a physical location or characteristic. A rock, this rock, that rock over there, basalt (a type of rock), a granite rock (a rock with an essential property), a wet rock (a rock with a temporary quality), Jim's rock (a rock with the quality of being possessed by a named entity) are not capitalized until named and uniqueness thus asserted or implied (e.g., Plymouth Rock, the Stone of Scone, the Willamette Stone, El Capitan, the Rock of Gibraltar, etc.)

I see two possibilities in Kubernetes documentation. 1) One of the early writers on the project did not know how to capitalize, and this became a thing people followed (not knowing any better), or 2) there is something people are trying to convey by capitalizing a short list of common nouns in Kubernetes documentation, but that meaning has not been clearly conveyed. In the first case, it's time to take a bold stand for ordinary language and get rid of this distraction once and for all. If, however, the latter is the case, I want to preserve this meaning, but need a rule I can enforce consistently.

[nigelpoulton]

My bad. My last comment was tongue-in-cheek making a play on words with "object" and the fact that P/pods S/services and the likes are K8s "objects".

In all seriousness though... I'm not passionate about this, other than from a consistency perspective.

When I write about Kubernetes, I replicate the case that is used in a YAML file. E.g. Kubernetes objects defined in the top-level kind field are capitalized in YAML files, so I capitalize them when I write. As an example, I capitalize Pod, Deployment, Service...but I do not capitalize container.

For me, it adds clarity for words with multiple meanings "service" and "deployment" obviously have other meanings. When capitalized, I'm always referring to the K8s API object, when not capitalized I'm not referring to the K8s version. This could be especially useful for people whose first language is not English. I make a living writing books and making training videos and reach a lot of people whose first language isn't English, so I sometimes go over the top to make myself extra clear -- sometimes that can be jarring, even for me.

Oh, and I also write ReplicaSet and never replica set etc.

I'm not saying it's correct, but it brings consistency and a reliable pattern.

Getting philosophical for a second about language... I'm excited to see how written English evolves and is influenced by non-native speakers. I used to go crazy when people would use "on premise" when they meant "on premises". These days I've given up and can see the day when when "on premise" is more widely used than the correct "on premises" to refer to equipment at premises you own/rent ;-)

@wabernatScality @theletterf

[nigelpoulton]

I just checked my Docker book, and what a mess it is. It's crying out for standardization like we're talking about.

The three main things that are messy in my Docker book are Compose/compose, Stack/stack, and Swarm/swarm. These all refer to Docker technologies as well as having wider meanings. I was less consistent with my use of capitalization and will most definitely fix that in the next edition.

[sftim]

https://kubernetes.io/docs/contribute/style/style-guide/ covers some of this. If it's not as clear as you'd like - we take pull requests!

[sftim]

The bit that gets me is https://kubernetes.io/docs/contribute/style/style-guide/#use-camel-case-for-api-objects

because it's not what most people know as camelCase, it's either PascalCase or UpperCamelCase (for example: CustomResourceDefinition, not customResourceDefinition).

[wabernat]

Funny you should mention it, I opened a bugfix request on the camelCase vs. PascalCase issue just yesterday.

I would be delighted to fire a PR your way, but I do not believe my solution to this problem (slavish devotion to, and ruthless enforcement of, the Chicago Manual of Style) will be at all welcome.

[tengqm]

Are everyone happy with this discussion? We do have some guidelines for docs ( https://kubernetes.io/docs/contribute/style/style-guide/#use-camel-case-for-api-objects) and there is a bugfix request raised in the broader community for clarification.

Can we close this now?

[tengqm]

Labeling this as an English issue, although some other languages may have similar questions. /language en

[wabernat]

I don't pretend to understand the internal reclassification of this issue. At this time, however, I am not satisfied, because I cannot yet see any clear rule about how to capitalize that I can reliably apply. Can you please include a link to the "bugfix request raised in the broader community"?

[tengqm]

@wabernatScality "by bugfix request raised", I was referring to the issue you raised here. Obviously this is not a docs-only issue. For example, in the API reference doc, we see many instances of PascalCase which should be camelCase as well. The related style guide in the website is documented here. Pull requests for improving that guideline are welcomed.

[wabernat]

Who is responsible for this page? I would like to enter into a dialog with this person to make for better conventions. If I "just issue a PR", I fear my suggestions will be either rejected outright or slow-marched until I abandon all hope. I will be happy to engage with anyone in the Kubernetes community to improve this section, but I have no confidence that the radical, yet necessary changes I propose will be taken seriously without a champion from within the k8s documentation community.

[sftim]

@wabernatScality there isn't one person responsible for the website - instead the documentation special interest group has responsibility.

If you want to, you can bring up this issue (or any other issue) during a weekly meeting. It's also fine to continue that discussion here.

[sftim]

This being open source, it's also fine to Just Do It and open your own pull request.

[wabernat]

With respect to this issue, one of two things is true: everything done to date has been wrong, or I am uninformed. The k8s community has adopted a customary capitalization that makes no sense to me, appears grounded to no enforceable rule, and the guidance offered on this page seems only there to reassure people preserving the customary capitalization without explaining to outsiders when or why one should employ it.

I want either clear guidance on the customary orthography (capitalizing apparently improper nouns such as "Pod," "Job," "Node," "Service", etc., except when you don't), or a frank expression of willingness to change the style guide and abandon this custom as untethered to any standard English usage. Given the leisurely pace a much simpler problem I pointed out has been working its way through the system, I do not foresee a PR timely producing either result.

If you honestly believe someone with a track record of zero completed PRs can change Kubernetes house style, I will give it a go, but it does seem pointless without interest and championship from someone inside the community.

[sftim]

I think most Kubernetes users and documentation contributors are happy seeing resource names (Pod, DaemonSet, EndpointSlice) capitalized in PascalCase, for the reasons already given.

Maybe the challenge instead is to make it clear to new readers why some terms are written that way, so that the common quality - these are the names of resources in the Kubernetes API - is more obvious.

[wabernat]

Tim: thanks for engaging with me thoughtfully on this issue. As an editor I generally do my best to preserve unorthodox capitalizations for neologisms and proper nouns. Camel and Pascal case are not exceptions: if there is a file or a setting set in an unusual case, I absolutely try to conserve it. Conversely, I deal with engineers who do not understand the rules of capitalization at all (not their job!), and I frequently encounter and must correct capitalization (or a lack thereof) that makes no sense or is inconsistent.

So... stipulating that there is a list of "resource names" that are capitalized though not proper names, I need to know a) Can anyone provide me with such a list? b) Are there any circumstances under which such names would not be capitalized? and c) As an editor with no expertise in Kubernetes and mere familiarity with Kubernetes concepts, how can I determine a correct "resource name" capitalization from any use of a term that would not merit such capitalization?

While Pascal case is easy enough to spot for words that appear in code sections or are compound words, this method falls apart on non-code, non-compound words. If I encounter the word "camelPod" or "PascalPod" in running text, I know to leave it alone, as it designates something so named in code. It is a proper name, and I handle it the same as I would handle "Captain America" or "e e cummings." If, however, I encounter "Pod" in running text, I cannot tell, as it is one word, whether it is Pascal case or simply capitalized and if so, whether capitalized correctly or incorrectly. The tests I've heard (Is it an object? Is it a resource?) are unilluminating and require specialized engineering knowledge. So we find ourselves in the current impasse: Engineers do not know the rules of capitalization (my job), yet the only people who can tell me whether to capitalize a term are engineers (not their job).

The problem here as I see it is that a custom has arisen to capitalize based on people's sentiments and tribal knowledge. I cannot fix this within the normal rules of grammar, because the custom violates those rules. I cannot enforce the custom (as I do for example with always-lowercase daemons) without some simple tests to apply, and those tests are not evident (and I strongly suspect this is because no one has given the problem serious thought).

This looks like problems I caused as a junior tech writer: once you make the error and enforce the error, undoing it becomes increasingly difficult until you find yourself maintaining and defending absurdities. In my own documentation, I simply refer to pods as pods and jobs as jobs, and the documentation is no less clear. I regret having to put you on the spot for this, because I know people would like this custom to continue, but if it is going to persist, it must be meaningfully codified. I do not know enough about the custom to codify it. I suspect no one can. And the only solution I see is to restore order by returning to a strict formalism that few will appreciate. So I don't believe filing a PR (to the effect of "You've all been doing it wrong! Do it my way!") will be especially productive.

[sftim]

[is there] a list of "resource names" that are capitalized though not proper names

Pretty much https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/ (the things listed in the left nav above fragment #-strong-definitions-strong)

Exceptions:

• container. Two reasons; one, you never kubectl create Container, you always create Pods.
• in any localization where the resource and the concept are the same name, you can use the lower case name to emphasize that you're not really talking about the API. For example: “this example Deployment provides multiple endpoints for accessing storage” vs. “this example Deployment provides multiple Endpoints for accessing storage”

That difference is why we use capitalization. An application deployment is not an application Deployment.

[wabernat]

Reviewing the items you have listed (scraping the left column to Definitions), I see the following non-compound words:

• Container
• Deployment
• Job
• Pod
• Endpoints
• Ingress
• Service
• Secret
• Volume
• Event
• Binding
• Lease
• Namespace
• Node
• Role

As a thought experiment, I invite you to visit the API reference you sent me, search any word on this list, and tell me if it is capitalized consistently, logically, and in a fashion that you find illuminating of the distinction you're trying to make by setting it in (truncated) Pascal case. I see little consistency, but I lack the expertise, for example, to divine the difference between the endpoints and services referenced in the following passages:

"publishNotReadyAddresses, when set to true, indicates that DNS implementations must publish the notReadyAddresses of subsets for the Endpoints associated with the Service."

Compare this to the immediately following definition:

"If empty or not present, the service is assumed to have an external process managing its endpoints, which Kubernetes will not modify."

Is the second sentence not following the "resource name" capitalization rule, or do "service" and "endpoints" have different referents in the second sentence? If so, by what criterion would a non-programmer editor determine whether the second sentence (or for that matter, the first one) are set correctly?

If you find yourself frustrated by this exchange, and if, as I expect, you find that your own reference documentation does not conform the standard you've set, might it be time to reassess this? As a much simpler rule, I recommend capitalizing proper nouns and leaving these "special" words to be capitalized according to the rules of English grammar. In my own writing, if I were to encounter an API named "Pod", I would capitalize it. Were I to encounter an object discussed generically, as with "Deployment," and "Endpoints" in your example, I would set it lowercase, except if the word is a proper noun (name) or code syntax. If it were syntax, I would set the case as indicated in the syntax, but also set the syntax as monospace code. If there is a "Deployment" API, it is a proper noun/name. It might be helpful to indicate the name's referent immediately after the name (the Deployment API, for example) but your standards appear to take a hard line against this practice, in favor of the (in my view flawed) capitalization standard.

I apologize if I seem obtuse. If it is any reassurance, I will tell you I am not being willfully dim, but I do believe that nailing down this point will make the documentation more comprehensible to a greater audience, and it will certainly help me in editing my house K8s implementation.

Thanks again for your thoughtful responses.

--William

[sftim]

@wabernatScality thanks for suggesting the switch to English grammar rules. I worry that adopting these rules would be unhelpful for the downstream localizations which largely do not heed English orthography. There are many more non-English localizations of these docs than the one English localization.

To force all audiences into the confines of English would to me not just seem unhelpful, it runs counter to explicit CNCF goals around inclusion. With that in mind I couldn't support, and I doubt many English-localization approvers would support, the switch you suggest.

[sftim]

You also asked:

do "service" and "endpoints" have different referents in the second sentence

Yes they do. Understanding these nuances and helping to communicate them to readers is tricky; that's one reason why technical writing is a distinct specialism. (BTW I do technical writing, but I'm not a technical writer by profession).

[wabernat]

Tim: Thanks again for taking the time to respond.

I do not think you have thought your worry all the way through. Downstream localizations are set in their own languages, each of which has its own rules and orthography. The German translator, for example, must capitalize all nouns, making no distinction for proper or improper nouns, as is customary in that language. Other languages (pictographic or ideographic languages, for example) do not have capital letters at all. Adopting an unorthodox orthography for English stands or falls only to the extent that it clarifies what's being described, in English. It makes no sense to adopt a peculiar English capitalization scheme to aid i18n because English capitalization is itself peculiar to English. You are, in effect, demanding that the translator understand two discrete capitalization schemes, English and Kubernetes. Therefore, I do not see sticking to standard English capitalization as exclusionary or adding any burden to translators. I invite you to ask any translators you work with to weigh in on this.

Concerning the example I raised, I came to the project seeking a rule or rules that I can apply, not airy appeals to nuance and trickiness. Technical writing is indeed a distinct specialty, and it is my profession. In the twenty-odd years that I have been doing this, I have repeatedly encountered attempts to bend the language or the typesetting to address a proximate issue, only to have the small-seeming amendment metastasize into a festering issue like the one I consider us to be viewing here. Invariably, these tales of woe reflect a lack of understanding of either technology or grammar, usually the latter, followed by a small sin (considering my project a "special case"), compounded by valiant attempts at consistency, plus time.

So I put the question to you again: As an editor, what rule can I apply to the "special" non-compound capitals on the list above to determine whether they are correctly capitalized or set lowercase in narrative text?

[sftim]

As an editor, what rule can I apply to the "special" non-compound capitals on the list above to determine whether they are correctly capitalized or set lowercase in narrative text?

Always capitalize resource names.

[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

[fejta-bot]

Stale issues rot after 30d of inactivity. Mark the issue as fresh with /remove-lifecycle rotten. Rotten issues close after an additional 30d of inactivity.

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 rotten

[theletterf]

Since this is being addressed elsewhere, I'm closing the issue. Thanks everyone for the incredibly fruitful conversation!