Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

revise style guidelines for capitalization #24645

Merged
merged 1 commit into from
Feb 7, 2021
Merged

revise style guidelines for capitalization #24645

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 14 additions & 11 deletions content/en/docs/contribute/style/style-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,22 +44,25 @@ The English-language documentation uses U.S. English spelling and grammar.

### Use upper camel case for API objects

When you refer specifically to interacting with an API object, use [UpperCamelCase](https://en.wikipedia.org/wiki/Camel_case), also known as Pascal Case. When you are generally discussing an API object, use [sentence-style capitalization](https://docs.microsoft.com/en-us/style-guide/text-formatting/using-type/use-sentence-style-capitalization).
When you refer specifically to interacting with an API object, use [UpperCamelCase](https://en.wikipedia.org/wiki/Camel_case), also known as Pascal case. You may see different capitalization, such as "configMap", in the [API Reference](/docs/reference/kubernetes-api/). When writing general documentation, it's better to use upper camel case, calling it "ConfigMap" instead.

When you are generally discussing an API object, use [sentence-style capitalization](https://docs.microsoft.com/en-us/style-guide/text-formatting/using-type/use-sentence-style-capitalization).

You may use the word "resource", "API", or "object" to clarify a Kubernetes resource type in a sentence.

Don't split the API object name into separate words. For example, use
PodTemplateList, not Pod Template List.

Refer to API objects without saying "object," unless omitting "object"
leads to an awkward construction.
The following examples focus on capitalization. Review the related guidance on [Code Style](#code-style-inline-code) for more information on formatting API objects.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think you need to describe what to expect in the following table. How about removing line 56?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added that line to offer an hint as to why code style appeared in the table, so I think it has a purpose.


{{< table caption = "Do and Don't - API objects" >}}
{{< table caption = "Do and Don't - Use Pascal case for API objects" >}}
Do | Don't
:--| :-----
The pod has two containers. | The Pod has two containers.
The HorizontalPodAutoscaler is responsible for ... | The HorizontalPodAutoscaler object is responsible for ...
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest

Suggested change
The HorizontalPodAutoscaler is responsible for ... | The HorizontalPodAutoscaler object is responsible for ...
The `HorizontalPodAutoscaler` is responsible for ... | The HorizontalPodAutoscaler object is responsible for ...

(and keep the line)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had purposely left out code style from the do/don't table, because I was wary of trying to illustrate two concepts at once.

I'm leaning toward using code style in the table, but I will add a link to the code style guidelines in the preceding paragraph.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Geoff has the instinct of correct. In the present example, "HorizontalPodAutoscaler" should be set only in code (in all examples) or not in code at all. Mixing them up only confuses two issues, and the reader. A brief spleen-dump concerning code formatting follows.

Once upon a time, monospace type was used to indicate command-line interactions and code snippets, full stop. Your guide now recommends it for paths, command tools, and component names. The present example adds Kubernetes objects to this list. This is a mistake: It feels like you're making a bright distinction, because you already know what you're trying to tell the reader, and putting it in monospace makes it stand out and look like documentation. In the present example, Pascal case already conveys quite clearly that the word HorizontalPodAutoscaler is an object, or at least is not an ordinary word (are objects considered components? Who adjudicates this?) Setting it in monospace adds no new meaning and burdens your writers and readers with another exceptional rule. As soon as someone copies and pastes the passage, the monospace signifier vanishes, leaving you where you started.

As @tengqm pointed out earlier, capitalization is a weak way of conveying information. Modifying typesetting is even weaker, especially when rules—however well-intentioned they may be—require its use to proliferate. (If every word is bold, no word is bold...)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is a good point about copy/paste.

I don't want to wade too deep into the code style debate here. The new draft page provides flexibility, and I think is a good next step.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't want to wade too deep into the code style debate here.

This PR should IMO either revise the code style recommendations or fit in with them. I'm not so keen on adding recommendations that conflict with other parts of the same page.

The easy option is to follow the current guidance on code style, and then if this merges come back and tweak it. It's the same idea as keeping PRs small that change source code: many small PRs that make incremental improvements, rather than one large change set that aims for perfection.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that the style guide now offers more styling options for API objects.

  • Do you need to show code styling in this section or could you state that the examples focus
    on capitalization and usage of general terms?
  • Is code styling of API objects optional? Is it acceptable to use code styling of a Kubernetes
    resource term that also adds "resource" or "object" after the term? Probably not.

Again, this section comments on how the API resource names/definitions are capitalized (which
matches how the name is used in the specification). This section also adds that it is acceptable to
add the word "object" after the term. Thirdly, the section adds that at times it is acceptable to use a general term (with sentence case) to refer to Kubernetes related software objects such as pod, node, secret, service, container.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @geoffcline . I'd like to move this PR forward or close it.
I think there is agreement with the guidance in the section on capitalization and API objects.
What do you think about limiting the examples? For example:

The HorizontalPodAutoscaler resource is responsible for ... | The Horizontal pod autoscaler is responsible for ...
A PodList object is a list of pods. | A Pod List object is a list of pods.
The Volume object contains a `hostPath` field. | The volume object contains a hostPath field.
Every ConfigMap object is part of a namespace. | Every configMap object is part of a namespace.
For managing confidential data, consider using the Secret API. | For managing confidential data, consider using the secret API.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One thing to watch out for: you can find a volume mentioned in Kubernetes in several places, but AIUI not as a resource in the HTTP API. I'm wary in case someone reads the style guide and ends up confused about how storage works.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK @sftim. Can you provide a concrete example?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could remove the "Volume" example. The examples I provided are "tests" of the recommendations.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

storage volume, volume plugin, a volume or logical drive, volume driver

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree on moving this forward or closing it.

I'm thinking I'll bring this up again at the next sig docs meeting to ask for synchronous feedback. I'll make a powerpoint slide with the new examples.

Regarding the volume example, I attempted to literally copy it from the API reference.

See, for example,

A PodList is a list of pods. | A Pod List is a list of pods.
The two ContainerPorts ... | The two ContainerPort objects ...
The two ContainerStateTerminated objects ... | The two ContainerStateTerminateds ...
geoffcline marked this conversation as resolved.
Show resolved Hide resolved
The HorizontalPodAutoscaler resource is responsible for ... | The Horizontal pod autoscaler is responsible for ...
A PodList object is a list of pods. | A Pod List object is a list of pods.
The Volume object contains a `hostPath` field. | The volume object contains a hostPath field.
Every ConfigMap object is part of a namespace. | Every configMap object is part of a namespace.
For managing confidential data, consider using the Secret API. | For managing confidential data, consider using the secret API.
{{< /table >}}


Expand Down Expand Up @@ -113,12 +116,12 @@ The copy is called a "fork". | The copy is called a "fork."

## Inline code formatting

### Use code style for inline code, commands, and API objects
### Use code style for inline code, commands, and API objects {#code-style-inline-code}

geoffcline marked this conversation as resolved.
Show resolved Hide resolved
For inline code in an HTML document, use the `<code>` tag. In a Markdown
document, use the backtick (`` ` ``).

{{< table caption = "Do and Don't - Use code style for inline code and commands" >}}
{{< table caption = "Do and Don't - Use code style for inline code, commands, and API objects" >}}
Do | Don't
:--| :-----
The `kubectl run` command creates a `Pod`. | The "kubectl run" command creates a pod.
Expand Down