Add title case style guideline #35990

shannonxtreme · 2022-08-15T21:16:36Z

Update the style guide to add guidance for title case in page titles

/sig docs
/language en
/cc @sftim

netlify · 2022-08-15T21:29:14Z

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`752defe`
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-main-staging/deploys/62fab7b5d3dfa00008e5ab25
😎 Deploy Preview	https://deploy-preview-35990--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

netlify · 2022-08-15T21:32:57Z

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`e688bb8`
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-main-staging/deploys/632b7a2a5cf65d00089a779f
😎 Deploy Preview	https://deploy-preview-35990--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

bradtopol · 2022-08-16T14:42:23Z

Assigning a SIG Docs Chair since this is trying to change the style guidelines.
/assign @natalisucks

natalisucks · 2022-08-16T18:14:42Z

@shannonxtreme Heya Shannon! 👋 Our style guide takes a lot of inspiration from the Google developer documentation style guide, which recommends sentence case for titles and headings. I'm wondering what the motivation is to take a different approach? If there's a conversation that yourself and Tim have had, my apologies in advance for not being aware of the context.

shannonxtreme · 2022-08-16T18:24:44Z

Ah @natalisucks I was trying to codify what I was seeing here: #35908 (comment)

I wasn't trying to change the guideline -- was trying to put the current convention in writing in our SG

natalisucks · 2022-08-16T18:54:22Z

@shannonxtreme Gotcha! It might not surprise you to hear that I don't agree with the suggested change in that comment 😂 Looking at the docs homepage for example, the all capitals convention isn't followed (at least mostly), and I would personally prefer consistency across the docs. However, I also see that capitalization is used across other areas of the docs very specifically (such as in our Concepts area, but not specifically in the Contribute section), so I'm now wondering what we decide on and try and ensure consistency from there.

TL;DR – We don't have a unified "current convention", but it is certainly a good idea to decide on one and stick with it.

Would be happy to hear your take @sftim if you feel strongly about this 😸

shannonxtreme · 2022-08-16T18:58:29Z

Fwiw I use the dev docs style guide a lot and agree with sentence case as well 😁 I think it's def helpful to have a place in our domain to point to in reviews if needed

shannonxtreme · 2022-08-16T19:52:29Z

Let's discuss what option we want to document in the async Slack (and thank you @bradtopol for tagging Natali!)

/hold

sftim · 2022-08-17T10:52:16Z

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

+{{< table caption = "Do and Don't - Use title case for page titles" >}}
+Do | Don't
+:--| :-----
+Kubernetes API Server Bypass Risks | Kubernetes API server bypass risks
+Configure a Security Context for a Pod or Container | Configure a security context for a Pod or container
+{{< /table >}}
+


Can we clarify that this is just for the title in the front matter, and not for headings within the page?

Should this convention apply to all titles, page and heading? I dont think that we have a guideline for headings (i couldn't see it in the style guide, please point it out to me if its there already) but it seems to be the general convention that we use in headings as well

We write headings (not titles) in sentence case.

The guidance on page titles could link to the advice on headings, maybe also vice versa?

Might be a good idea to merge the titles section into the heading section, call it "Headings and titles" maybe, and clarify what works where.

And I'd still like us to discuss changing the guidance for titles to use sentence case as well, but perhaps as a separate issue. The 5 votes that got in Slack arent many though

sftim · 2022-08-17T10:53:36Z

@natalisucks to me this isn't a change; it's codifying the existing convention (which is not that well followed or as well known).

I learned that convention from approvers / reviewers telling me about it.

sftim · 2022-08-17T10:55:39Z

I'd kind of like to merge this PR so it becomes part of the style guide history, even if we then decide we want to change from that convention.

That'll help someone looking for a answer to a question like “Hmm, when did we adopt the previous convention and what was our thinking when we did”.

reylejano · 2022-08-26T18:37:55Z

I agree that we should document that title case is used for the front matter title
We should be clear to differentiate front matter title vs headings
Maybe prepend the example with title:
or have a larger example like this from the configmaps concepts page

title: ConfigMaps
content_type: concept
weight: 20

sftim · 2022-08-27T14:02:27Z

The title of the ConfigMaps page is, unfortunately, both sentence case and title case (due to our guidelines about how to capitalize API kinds). Maybe a different example?

shannonxtreme · 2022-09-13T16:26:44Z

@sftim and @reylejano I merged this into the headings section which I renamed to Headings and titles (added an anchor to not break links). I prepended the example with title: to make it clear we mean the frontmatter.

shannonxtreme · 2022-09-13T20:43:06Z

/unhold

chrismetz09 · 2022-09-13T21:50:41Z

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

+Use sentence case for headings in the page body. For example, **Extend kubectl
+with plugins** | Use title case for headings in the page body. For example,


Bold tags appearing as text in preview.

chrismetz09 · 2022-09-13T21:57:25Z

Contribute
FWIW, I followed the google dev style guide when I was working on the contribute section - Use sentence case for all headings.

shannonxtreme · 2022-09-13T22:00:25Z

Contribute
FWIW, I followed the google dev style guide when I was working on the contribute section - Use sentence case for all headings.

Yeah I will open a new issue that we can use to implement that as official guidance for both headings and titles!

natalisucks · 2022-09-18T19:52:56Z

Thanks for following up with this, @shannonxtreme! Given the feedback throughout the PR, I'm happy to sign-off on this being added to make our style guide clearer.
/lgtm

k8s-ci-robot · 2022-09-18T19:53:01Z

LGTM label has been added.

Git tree hash: a117a41516e6fdb01d46b67252a2d8b4812e8567

chrisnegus

Small wording suggestion.

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

shannonxtreme · 2022-09-28T16:04:17Z

This is ready for review :)

natalisucks · 2022-09-29T13:26:29Z

/lgtm

k8s-ci-robot · 2022-09-29T13:26:35Z

LGTM label has been added.

Git tree hash: 57285ccdda0ec85c281b8c7123a942e1168636be

sftim · 2022-10-22T08:51:45Z

I'd kind of like to merge this PR so it becomes part of the style guide history, even if we then decide we want to change from that convention.

That'll help someone looking for a answer to a question like “Hmm, when did we adopt the previous convention and what was our thinking when we did”.

/approve

We can track a new(?) issue to change this guidance

k8s-ci-robot · 2022-10-22T08:52:04Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: sftim

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~~ [sftim]

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

k8s-ci-robot requested a review from sftim August 15, 2022 21:16

shannonxtreme force-pushed the patch-3 branch from 752defe to 9898a99 Compare August 15, 2022 21:21

k8s-ci-robot removed the do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. label Aug 15, 2022

k8s-ci-robot assigned natalisucks Aug 16, 2022

k8s-ci-robot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Aug 16, 2022

sftim reviewed Aug 17, 2022

View reviewed changes

shannonxtreme force-pushed the patch-3 branch 2 times, most recently from 80a1946 to 9c777bf Compare September 13, 2022 16:25

k8s-ci-robot added size/S Denotes a PR that changes 10-29 lines, ignoring generated files. and removed size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. labels Sep 13, 2022

shannonxtreme requested a review from sftim September 13, 2022 16:27

k8s-ci-robot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Sep 13, 2022

chrismetz09 reviewed Sep 13, 2022

View reviewed changes

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Sep 18, 2022

natalisucks mentioned this pull request Sep 20, 2022

Update page title of operator.md to APA style 'Title Case Capitalization'. #36885

Closed

chrisnegus reviewed Sep 20, 2022

View reviewed changes

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

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

shannonxtreme force-pushed the patch-3 branch from 9c777bf to 8a7f4b6 Compare September 21, 2022 20:54

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Sep 21, 2022

k8s-ci-robot requested a review from natalisucks September 21, 2022 20:54

k8s-ci-robot added size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. and removed size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Sep 21, 2022

Add title case style guideline

e688bb8

shannonxtreme force-pushed the patch-3 branch from 8a7f4b6 to e688bb8 Compare September 21, 2022 20:55

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Sep 29, 2022

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Oct 22, 2022

k8s-ci-robot merged commit 8eb5e46 into kubernetes:main Oct 22, 2022

chrisnegus mentioned this pull request Oct 24, 2022

Improper case usage on Titles and Headings #37487

Closed

shannonxtreme deleted the patch-3 branch November 25, 2022 21:10

		Use sentence case for headings in the page body. For example, **Extend kubectl
		with plugins** \| Use title case for headings in the page body. For example,

Add title case style guideline #35990

Add title case style guideline #35990

Uh oh!

Conversation

shannonxtreme commented Aug 15, 2022

Uh oh!

netlify bot commented Aug 15, 2022

✅ Pull request preview available for checking

Uh oh!

netlify bot commented Aug 15, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull request preview available for checking

Uh oh!

bradtopol commented Aug 16, 2022

Uh oh!

natalisucks commented Aug 16, 2022

Uh oh!

shannonxtreme commented Aug 16, 2022

Uh oh!

natalisucks commented Aug 16, 2022

Uh oh!

shannonxtreme commented Aug 16, 2022

Uh oh!

shannonxtreme commented Aug 16, 2022

Uh oh!

sftim Aug 17, 2022

Choose a reason for hiding this comment

Uh oh!

a-mccarthy Aug 18, 2022

Choose a reason for hiding this comment

Uh oh!

sftim Aug 18, 2022

Choose a reason for hiding this comment

Uh oh!

sftim Aug 18, 2022

Choose a reason for hiding this comment

Uh oh!

shannonxtreme Aug 18, 2022

Choose a reason for hiding this comment

Uh oh!

sftim commented Aug 17, 2022

Uh oh!

sftim commented Aug 17, 2022

Uh oh!

reylejano commented Aug 26, 2022

title: ConfigMaps content_type: concept weight: 20

Uh oh!

sftim commented Aug 27, 2022

Uh oh!

shannonxtreme commented Sep 13, 2022

Uh oh!

shannonxtreme commented Sep 13, 2022

Uh oh!

chrismetz09 Sep 13, 2022

Choose a reason for hiding this comment

Uh oh!

chrismetz09 commented Sep 13, 2022

Uh oh!

shannonxtreme commented Sep 13, 2022

Uh oh!

natalisucks commented Sep 18, 2022

Uh oh!

k8s-ci-robot commented Sep 18, 2022

Uh oh!

chrisnegus left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

shannonxtreme commented Sep 28, 2022

Uh oh!

natalisucks commented Sep 29, 2022

Uh oh!

k8s-ci-robot commented Sep 29, 2022

Uh oh!

sftim commented Oct 22, 2022

Uh oh!

k8s-ci-robot commented Oct 22, 2022

Uh oh!

Uh oh!

netlify bot commented Aug 15, 2022 •

edited

Loading

title: ConfigMaps
content_type: concept
weight: 20