Add fact sheets for key API kinds

[sftim]

This is an umbrella issue

What would you like to be added

Include a fact sheet for the Deployment and the Deployment controller. The fact sheet will condense the behavior of the Deployment controller into a concise set of statements about behavior, guarantees, and steady state. Use the Deployment topic as a prototype for how to write a fact sheet. Eventually, advocate for the use of fact sheets in all controller topics.

(from issue https://github.com/kubernetes/website/issues/12082)

This issue is a request to define fact sheet pages for key API kinds that developers interact with, such as (some or all of):

• Deployment
• ConfigMap
• CronJob
• Ingress
• Gateway
• Service
• PodDisruptionBudget
• HorizontalPodAutoscaler
• VerticalPodAutoscaler
• PriorityClass

Why is this needed

Fact sheets would help readers learn the basics of a particular topic (and the API that backs it). We shouldn't expect readers to read through a whole, lengthy topic page; nor should we assume that they have time to run through a tutorial, when they want to learn or relearn an API that helps them do a specific thing.

Fact sheets should include:

• a link to the full API reference
• a brief introduction to the concept (maybe reusing the glossary definition)
• at least one valid and tested example manifest, with good comments
• a summary of how the control plane works with the defined API, that follows a consistent writing style
• hyperlinks to key explanations within related concept and task pages

We should therefore also add a page to the docs contribution guide, that explains how to write factsheets and how to review PRs that add fact sheets.

Comments

• I'm assuming that we'd want to define a shortcode for the factsheet, and a mechanism to have the factsheet as a separate Markdown file.

• We could use a <details open="open"> element or similar to provide a fact sheet that is visible by default, but easy to fold away if the reader wants to read past it. We can also provide a CSS or JavaScript mechanism to add a separate Hide button after the factsheet, again for convenience.

• We might want to add fact sheets initially as drafts and then take those out of draft once several fact sheets are done and ready to launch

[sftim]

If this goes stale, I plan to close it.

[devarsh10]

Hey @sftim, I would like to work on this. By adding the required things. Like, giving intro. to concept, summary of how control plane works & by providing respective hyperlinks.

Regards.

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle rotten
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue with /reopen
• Mark this issue as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close not-planned

[k8s-ci-robot]

@k8s-triage-robot: Closing this issue, marking it as "Not Planned".

In response to [this](https://github.com/kubernetes/website/issues/38682#issuecomment-1616424639): >The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs. > >This bot triages issues according to the following rules: >- After 90d of inactivity, `lifecycle/stale` is applied >- After 30d of inactivity since `lifecycle/stale` was applied, `lifecycle/rotten` is applied >- After 30d of inactivity since `lifecycle/rotten` was applied, the issue is closed > >You can: >- Reopen this issue with `/reopen` >- Mark this issue as fresh with `/remove-lifecycle rotten` >- Offer to help out with [Issue Triage][1] > >Please send feedback to sig-contributor-experience at [kubernetes/community](https://github.com/kubernetes/community). > >/close not-planned > >[1]: https://www.kubernetes.dev/docs/guide/issue-triage/ 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.

[sftim]

Also see https://github.com/kubernetes/website/issues/42246

[sftim]

/area web-development

I will reopen this as stale /reopen /remove-lifecycle rotten /lifecycle stale

[k8s-ci-robot]

@sftim: Reopened this issue.

In response to [this](https://github.com/kubernetes/website/issues/38682#issuecomment-1654037194): >/area web-development > >I will reopen this as stale >/reopen >/remove-lifecycle rotten >/lifecycle stale 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.

[sftim]

/triage accepted

[vaibhav2107]

/remove-lifecycle stale

[sftim]

Want to work on this? See https://github.com/kubernetes/website/issues/43832 for a starting point.

[sftim]

/lifecycle frozen

[sftim]

Also see https://github.com/kubernetes/website/issues/46424