search

kubernetes / website

Kubernetes website and documentation repo:
https://kubernetes.io
Creative Commons Attribution 4.0 International
4.48k stars 14.41k forks source link

Improve wording for “What is Kubernetes” #32828

Open kenhtanaka opened 2 years ago

kenhtanaka commented 2 years ago

In the section titled "Why you need Kubernetes and what it can do" the first bullet point reads:

I'm not clear on the meaning here with regards to load balancing being a benefit with one container. I'm new to Kubernetes, but I assume that multiple containers make more sense. Would this be an accurate rewrite?

sftim commented 2 years ago

/retitle Improve working for “What is Kubernetes” /language en

The original wording is more appropriate. Balancing, whether it's network traffic, a finance ledger, or weights on beam, is something done in aggregate.

Additionally, the thing that Kubernetes directs traffic to is actually a different endpoint - usually a Pod. It's OK to be simple but the more detail we add to this overview, it becomes more problematic not to cover the full detail.

I like having a simple summary that doesn't yet include all the detail. We could look for a different wording that implies that the one overloaded container might be part of a broader set of some kind (without mentioning the actual implementation details: ReplicaSet, Deployment, etc).

kenhtanaka commented 2 years ago

I see, "Balancing" implies an aggregate action to me too, so with regards to "a container" I wasn't sure if I was making the right assumption that "there must be other containers" to make that work. I think this would be clearer to me to identify a broader set (change in italics):

Would that wording meet your goal of keeping a simple summary that is still accurate?

sftim commented 2 years ago

/retitle Improve wording for “What is Kubernetes”

How about: Service discovery and load balancing Kubernetes can expose a container using the DNS name or using their own IP address. When there are multiple containers backing a service, Kubernetes is able to load balance and distribute the network traffic. Load balancing helps ensure that a workload can stay available even if one container stops working, or during deployments.

kenhtanaka commented 2 years ago

Yes, that reads much clearer to me.

sftim commented 2 years ago

/triage accepted /kind cleanup

mehabhalodiya commented 2 years ago

/good-first-issue

nitishfy commented 2 years ago

/assign

nitishfy commented 2 years ago

Hey @sftim , I've opened the PR for this issue. Kindly look at it and feel free to suggest some changes if necessary.

sftim commented 2 years ago

I've reviewed the PR for this issue. Kindly look at it and feel free to suggest some changes if necessary.

English nit: you've opened a PR and are requesting a review.

nitishfy commented 2 years ago

@sftim My bad! Sorry, I mean I've made changes to the PR as required so now I'm asking for review if any further changes are required to be made before merging.

sftim commented 2 years ago

/remove-help

We shouldn't label updates to the What Is Kubernetes page as good first issues, unless the fixes are genuinely trivial. Updates to that page always require extra review.

nitishfy commented 2 years ago

I think we can close this issue. WDYT @sftim ?

kenhtanaka commented 2 years ago

As @sftim commented on Apr 13, does this change when merged? I'm not familiar with your workflow on when https://kubernetes.io/docs/concepts/overview/ will change.

k8s-triage-robot commented 1 year ago

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

This bot triages issues and PRs according to the following rules:

You can:

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

/lifecycle stale

sftim commented 1 year ago

/remove-lifecycle stale

BTW, once someone merges a fix for this issue, we can close the issue. I think there is room to improve the wording in https://kubernetes.io/docs/concepts/overview/

nitishfy commented 1 year ago

@sftim As far as the last comment by @reylejano (https://github.com/kubernetes/website/pull/34037#issuecomment-1226797408) , Do you think that any change is required?

sftim commented 1 year ago

I still think we should make an improvement (see my previous comment). It needs to be a change that reviewers agree is a benefit to the Kubernetes docs.

k8s-triage-robot commented 3 months ago

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

You can:

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

/remove-triage accepted

k8s-triage-robot commented 1 day ago

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

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

You can:

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

/lifecycle stale