Tweak wording for Workloads overview #24602

sftim · 2020-10-16T13:57:24Z

Revise introduction to Workloads concept [preview].

Follows on from PR #23737

netlify · 2020-10-16T14:09:50Z

Deploy preview for kubernetes-io-master-staging ready!

Built with commit aa27de5

https://deploy-preview-24602--kubernetes-io-master-staging.netlify.app

kbhawkey · 2020-10-16T17:21:29Z

content/en/docs/concepts/workloads/_index.md

 These resources configure {{< glossary_tooltip term_id="controller" text="controllers" >}}
-that make sure the right number of the right kind of Pod are running, to match the state
+that make sure the right number of the right kind of `Pod` are running, to match the state


@sftim , Can you explain the updates to the resource names? I'd like to understand if this is a change to the style guide?

The style guide was updated: 826d53c

What do you think? Does this change make the page easier to follow, or harder?

It is easier to have an explicit style rule that defines something like, "always add code formatting to API resource terms and always use the API term in the content as capitalized in the code".
It is not always clear when a common term like Pod needs to use capitalization. Often a page overuses the pod term. Some of the styling of the term Pod in the page could be removed, otherwise the page starts to look like a gameboard?
Per the style guide, the other API terms use code styling. Hopefully the added styling helps readers and does not detract from reading the page.

kbhawkey · 2020-10-20T19:10:16Z

@sftim
Looking at the preview, there are many formatting changes.
Also, there is a lot of information pushed into an index page.
I'd almost rather see a one sentence description (hints) about each workload (and any additional links) to get the reader to the individual page/section.
What do I think about the code formatting?
There are twenty-three resources formatted as code , several glossary tooltips, and ~sixteen intra-site links.
The page somewhat excessively uses resource terms.
There are some instances where you could have used "ingress" over Ingress (node vs Node)?
Page preview:
https://deploy-preview-24602--kubernetes-io-master-staging.netlify.app/docs/concepts/workloads/

sftim · 2020-10-20T22:45:47Z

I invite reviewers to compare:

Which is better? If it's the second one: merge this, then iterate.

sftim · 2020-10-20T22:56:58Z

/approve cancel

kbhawkey · 2020-11-16T19:30:28Z

content/en/docs/concepts/workloads/_index.md

+In the wider Kubernetes ecosystem, you can find third-party workload resources that provide
+additional behaviors. Using a
+[custom resource definition](/docs/concepts/extend-kubernetes/api-extension/custom-resources/),
+you can add in a third-party workload resource if you want a specific behavior that's not part


Should you reference,
https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#customresourcedefinition-v1-apiextensions-k8s-io

I'd rather link to the concept than the API details, especially whilst the API details don't hyperlink back to the concept.

kbhawkey · 2020-11-16T19:37:06Z

content/en/docs/concepts/workloads/_index.md

-Pod is running means that all the Pods on that node fail. Kubernetes treats that level
-of failure as final: you would need to create a new Pod even if the node later recovers.
+`Pods` have a [defined lifecycle](/docs/concepts/workloads/pods/pod-lifecycle/).
+For example, once a `Pod` is running in your cluster then a critical fault on the


Is it possible to use lowercase for some of the pod terms in lines 15-19?
Line 12 is clear.

tengqm · 2020-11-17T01:11:03Z

content/en/docs/concepts/workloads/_index.md

+additional behaviors. Using a
+[custom resource definition](/docs/concepts/extend-kubernetes/api-extension/custom-resources/),
+you can add in a third-party workload resource if you want a specific behavior that's not part
+of Kubernetes itself. For example, if you want the ability to specify a task that runs just once


not part of Kubernetes itself

This is not accurate. The more common way is

not part of Kubernetes core

tengqm · 2020-11-17T01:11:52Z

content/en/docs/concepts/workloads/_index.md

+[custom resource definition](/docs/concepts/extend-kubernetes/api-extension/custom-resources/),
+you can add in a third-party workload resource if you want a specific behavior that's not part
+of Kubernetes itself. For example, if you want the ability to specify a task that runs just once
+at a specific future date, neither `Job` nor `CronJob` is right for that - but you can implement or


No. This can be done using CronJob.

Please think of a different example.

tengqm · 2020-11-17T01:15:14Z

content/en/docs/concepts/workloads/_index.md

+  [`PersistentVolume`](/docs/concepts/storage/persistent-volumes/), and replicate both
+  the pods and their storage across different failure zones. Your code, running in the `Pods`,


This introduction has gone too far from the core concept of StatefulSet. Multi-zone deployment is not limited to stateful apps. It is a different topic from stateful.

sftim · 2020-11-23T09:25:10Z

I'll move this back to Draft to mark that there's tweaks to make.

sftim · 2020-12-08T23:46:57Z

I'd like another review on this (not urgent).

onlydole

This looks good to me, thank you @sftim!

k8s-ci-robot · 2020-12-18T12:49:35Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: onlydole

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

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

kbhawkey · 2020-12-18T19:00:01Z

content/en/docs/concepts/workloads/_index.md

+  `Deployment` is a good fit for managing a stateless application workload on your cluster,
+  where any `Pod` in the `Deployment` is interchangeable and can be replaced if needed.
+* [`StatefulSet`](/docs/concepts/workloads/controllers/statefulset/) lets you
+  run one or more related Pods that do track state somehow. For example, if your workload


nit: rephrase/replace: that do track state somehow. The use of "somehow" makes me think twice.
StatefulSet workload resources let you manage stateful applications.

kbhawkey · 2020-12-18T19:03:24Z

@sftim. I think the updates look good. There are a few places where "Pod" and "pod" have been switched up.
I like the additional content, though, would push further details to the actual content pages.
@tengqm , What do you think about the latest changes?
/lgtm
/hold

k8s-ci-robot · 2020-12-18T19:03:38Z

LGTM label has been added.

Git tree hash: 6bced388dcbe1b24ca34b0dd38e10bb71e77650e

tengqm · 2020-12-19T02:52:16Z

/lgtm

kbhawkey · 2020-12-19T11:56:33Z

/hold cancel

k8s-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Oct 16, 2020

k8s-ci-robot requested review from onlydole and zparnold October 16, 2020 13:57

k8s-ci-robot added language/en Issues or PRs related to English language sig/docs Categorizes an issue or PR as relevant to SIG Docs. labels Oct 16, 2020

sftim marked this pull request as ready for review October 16, 2020 13:58

k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Oct 16, 2020

kbhawkey reviewed Oct 16, 2020

View reviewed changes

sftim force-pushed the 20201015_tweak_workloads_concept_overview branch from 712b525 to ca38a6f Compare October 20, 2020 22:47

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

k8s-ci-robot added needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. and removed approved Indicates a PR has been approved by an approver from all required OWNERS files. labels Oct 20, 2020

sftim force-pushed the 20201015_tweak_workloads_concept_overview branch from ca38a6f to dd53659 Compare October 23, 2020 13:22

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Oct 23, 2020

kbhawkey reviewed Nov 16, 2020

View reviewed changes

tengqm reviewed Nov 17, 2020

View reviewed changes

sftim marked this pull request as draft November 23, 2020 09:25

k8s-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Nov 23, 2020

sftim force-pushed the 20201015_tweak_workloads_concept_overview branch from dd53659 to 7e3338e Compare December 8, 2020 23:35

Tweak wording for Workloads overview

aa27de5

sftim force-pushed the 20201015_tweak_workloads_concept_overview branch from 7e3338e to aa27de5 Compare December 8, 2020 23:46

sftim marked this pull request as ready for review December 8, 2020 23:46

k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Dec 8, 2020

onlydole approved these changes Dec 18, 2020

View reviewed changes

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Dec 18, 2020

kbhawkey reviewed Dec 18, 2020

View reviewed changes

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

k8s-ci-robot assigned kbhawkey Dec 18, 2020

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

k8s-ci-robot assigned tengqm Dec 19, 2020

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

k8s-ci-robot merged commit 9b35120 into kubernetes:master Dec 19, 2020

sftim deleted the 20201015_tweak_workloads_concept_overview branch September 12, 2021 10:50

sftim mentioned this pull request Dec 7, 2022

Improve overview for workload APIs #37593

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Tweak wording for Workloads overview #24602

Tweak wording for Workloads overview #24602

sftim commented Oct 16, 2020 •

edited

Loading

netlify bot commented Oct 16, 2020 •

edited

Loading

kbhawkey Oct 16, 2020

sftim Oct 17, 2020

kbhawkey Nov 16, 2020

kbhawkey commented Oct 20, 2020

sftim commented Oct 20, 2020

sftim commented Oct 20, 2020

kbhawkey Nov 16, 2020

sftim Dec 8, 2020

kbhawkey Nov 16, 2020

tengqm Nov 17, 2020

tengqm Nov 17, 2020

tengqm Nov 17, 2020

sftim commented Nov 23, 2020

sftim commented Dec 8, 2020

onlydole left a comment

k8s-ci-robot commented Dec 18, 2020

kbhawkey Dec 18, 2020 •

edited

Loading

kbhawkey commented Dec 18, 2020

k8s-ci-robot commented Dec 18, 2020

tengqm commented Dec 19, 2020

kbhawkey commented Dec 19, 2020

		[`PersistentVolume`](/docs/concepts/storage/persistent-volumes/), and replicate both
		the pods and their storage across different failure zones. Your code, running in the `Pods`,

Tweak wording for Workloads overview #24602

Tweak wording for Workloads overview #24602

Conversation

sftim commented Oct 16, 2020 • edited Loading

netlify bot commented Oct 16, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kbhawkey commented Oct 20, 2020

sftim commented Oct 20, 2020

sftim commented Oct 20, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sftim commented Nov 23, 2020

sftim commented Dec 8, 2020

onlydole left a comment

Choose a reason for hiding this comment

k8s-ci-robot commented Dec 18, 2020

kbhawkey Dec 18, 2020 • edited Loading

Choose a reason for hiding this comment

kbhawkey commented Dec 18, 2020

k8s-ci-robot commented Dec 18, 2020

tengqm commented Dec 19, 2020

kbhawkey commented Dec 19, 2020

sftim commented Oct 16, 2020 •

edited

Loading

netlify bot commented Oct 16, 2020 •

edited

Loading

kbhawkey Dec 18, 2020 •

edited

Loading