kubernetes / kubernetes/website

Add fact sheets for key API kinds

Open
#38,682 15 comments 0 reactions 0 assignees View on GitHub
area/web-development kind/feature triage/accepted
Dominant language
HTML
Stars
5.4k
Forks
15.7k
Avg merge
4d 18h
Merged PRs (30d)
204

Description

_**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 `` 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

Contributor guide

Open the contributing guide

Research direction

Start by reading the Deployment topic identified as the prototype and the linked issue from which this request originated. Review the proposed fact-sheet contents and the Kubernetes documentation contribution guide, then define a focused scope for one API kind; done should include an agreed fact-sheet format, tested example manifest, API reference links, and contribution guidance.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.