Expand the Style Guide to improve consistency in docs and comms

[shannonxtreme]

We should expand the Contributor Style Guide so that contributors have a reference for common terms and phrases.

Some examples of what we could add:

• Making the distinction between "deprecating" an API and "removing" an API (#28690)
• Saying "manifest" vs "definition" or "spec" and other terms with multiple technically correct alternatives
• Pod vs pods (capitalization especially w.r.t the plural version of a word)
• When to use inline codeblocks vs just saying the resource name (eg: VerticalPodAutoscaler vs Vertical Pod Autoscaler) and whether to use the word "object" or "resource" after a code-blocked mention (eg: Create a Service object vs Create a Service)

A lot of the groundwork already exists in the current Style Guide, but it could use expansion and potential reorganization.

We could, for example, organize into sections based on type of style issue (grammar/accessibility & inclusion/formatting/API).

This may be a long term priority but I thought it might be a good discussion point for a future meeting as it has the potential to be a pain to maintain as it grows, but would be invaluable for new contributors (like me!).

Related issues

• 26190

• 18231

• 14101

• 7030

• 5234

• 20862

• 20925

Tasks

• [ ] Expand capitalization rules and use cases
• [ ] Expand/create an API conventions and formatting guide (see #26190)
• [ ] Review list of current Hugo shortcodes and prune/update
• [ ] Add content from the k/community style guide (see #14101)
• [ ] Expand use cases for bold, italics, and other formatting/readability components (see #7030)
• [ ] Add style guide entry for Release Notes (see #5234)
• [ ] Document label names (see #20925)

/cc @sftim

[shannonxtreme]

/assign /sig docs

[sftim]

/triage accepted /lifecycle frozen

[sftim]

/priority backlog /sig contributor-experience

[k8s-triage-robot]

This issue has not been updated in over 1 year, and should be re-triaged.

You can:

• Confirm that this issue is still relevant with /triage accepted (org members only)
• Close this issue with /close

For more details on the triage process, see https://www.kubernetes.dev/docs/guide/issue-triage/

/remove-triage accepted

[k8s-ci-robot]

This issue is currently awaiting triage.

SIG Docs takes a lead on issue triage for this website, but any Kubernetes member can accept issues by applying the triage/accepted label.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.

[natalisucks]

@shannonxtreme I'd love to hear from you if you think this issue is worth reviving. At the moment, many of the relevant issues you've mentioned have been closed due to inactivity, and this umbrella issue would need an overhaul to have it linked to relevant work in flight (or not). While I do think this work is important, we can absolutely reflect as such in a new issue

[natalisucks]

Coming back to this issue, and in the interest of cleaning up some of our older work, I am in favour of closing this given the amount of inactivity in the linked relevant work, and the overhaul required to make this umbrella issue suitable for our current docs scope.

Happy to hear feedback from others!

[shannonxtreme]

Yeah I think we should close this. If I have more time down the line I'll bring it up at a sig meeting 😁 I think that we covered a lot of this in the linked issues so I see it as a win still!

[natalisucks]

Agreed, thanks @shannonxtreme! 🎉 /close