Tidy concepts section post-Docsy #21997

sftim · 2020-06-22T22:23:00Z

Tidy the Concepts section following the switch to Docsy.
Preview.

give every subsection directly below Concepts a description
Where an existing Concept section has an index and the first page is “Overview of X”, move the content of that overview into the index page itself.
and tidy one note to use a shortcode

sftim · 2020-06-22T22:23:27Z

Prompted by #21815 (comment)

sftim · 2020-06-22T22:29:58Z

Helps with #21755

netlify · 2020-06-22T22:34:22Z

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

Built with commit 4a4719d

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

kbhawkey · 2020-06-24T12:29:03Z

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

@@ -1,5 +1,6 @@
 ---
 title: "Containers"
 weight: 40
+description: Technology for packaging the (compiled) code for an application along with the dependencies it needs at run time


nits:
Sentence does not end with period.
compiled
Technology for packaging the ... . How is this page different from the general definition of containers, such as,
https://docs.microsoft.com/en-us/dotnet/architecture/microservices/container-docker-introduction/

This text is borrowed from https://kubernetes.io/docs/concepts/containers/overview/
I was going to leave wording changes for a follow-up PR.

I'm happy to use different wording here; do you have something in mind?

kbhawkey · 2020-06-24T13:18:06Z

content/en/docs/concepts/overview/components.md

@@ -3,6 +3,9 @@ reviewers:
 - lavalamp
 title: Kubernetes Components
 content_type: concept
+description: >
+  A Kubernetes cluster consists of a set of worker machines, called nodes , that run containerized applications. Every cluster has at least one worker node.


nit: Could the text be simplified? The paragraph identifies nodes and control plane but describes them separately.
A cluster needs a control plane component as well as a node?
Here is one way to edit:
A Kubernetes cluster consists of a set of machines called nodes. [is this needed: Every cluster has at least one node.]
The nodes host the Pods that represent the application components and run the containerized applications. The control plane manages the nodes and the Pods in the cluster. In production environments, the control plane usually runs across multiple computers and a cluster usually runs multiple nodes, providing fault-tolerance and high availability.

kbhawkey · 2020-06-24T13:29:34Z

content/en/docs/concepts/services-networking/_index.md

@@ -1,5 +1,11 @@
 ---
 title: "Services, Load Balancing, and Networking"
 weight: 60
+description: >
+  Kubernetes networking addresses four concerns.
+  Containers within a Pod use networking to communicate via loopback.


Do the four concerns follow? If so, could you use a colon after ... four concerns?

I'm not sure how the rendered page would look.

Kubernetes networking addresses four concerns: Containers within a Pod use networking to communicate via loopback. Cluster networking provides communication between different Pods. The Service resource lets you expose an application running in Pods to be reachable from outside your cluster. You can also use Services to publish services only for consumption inside your cluster.

?

Please shorten description. Something like:
Cluster services and networking expose applications to external services and enable communication between Pods.

kbhawkey · 2020-06-24T13:47:42Z

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

@@ -1,5 +1,9 @@
 ---
 title: "Storage"
 weight: 70
+description: >
+  Kubernetes provides both long-term and ephemeral storage that you can make available to Pods.


nit: there are several you can phrases in the paragraph.
A quick edit:
Kubernetes provides both long-term and ephemeral storage. Pods interface with the
storage resources to persist and maintain the state of applications.
Stateful applications in your cluster rely upon durable storage. You can also configure
different classes of storage and automate how these are provisioned.

Please shorten. Possible edit:
Kubernetes provides both long-term and ephemeral storage.

kbhawkey · 2020-06-24T13:54:36Z

content/en/docs/concepts/_index.md

-
-## Kubernetes Control Plane
-
-The various parts of the Kubernetes Control Plane, such as the Kubernetes Master and kubelet processes, govern how Kubernetes communicates with your cluster. The Control Plane maintains a record of all of the Kubernetes Objects in the system, and runs continuous control loops to manage those objects' state. At any given time, the Control Plane's control loops will respond to changes in the cluster and work to make the actual state of all the objects in the system match the desired state that you provided.


Q: What happens to this content? I agree that much of this should be edited.
I can't recall, but did you have another pull request to tweak this content.

The way I see it, this content goes - at least for now. It doesn't seem that useful to keep given how Docsy renders the section links.

What I could do is add an explicit link into https://deploy-preview-21997--kubernetes-io-master-staging.netlify.app/docs/concepts/overview/what-is-kubernetes/

Does that work?

kbhawkey · 2020-06-24T14:02:24Z

content/en/docs/concepts/scheduling-eviction/_index.md

@@ -1,5 +1,8 @@
 ---
 title: "Scheduling and Eviction"
 weight: 90
+description: >
+  In Kubernetes, scheduling refers to making sure that Pods are matched to Nodes so that the kubelet can run them.
+  Eviction is the process of proactively failing one or more Pods on resource-starved Nodes.


nit: This could be reworded.
Quick edit:
In Kubernetes, scheduling refers to managing the assignment of Pods to Nodes based on scheduling policies and available resources.

Please reduce.
Kubernetes schedules and evicts Pods to a match available resources.

Kubernetes schedules and evicts Pods to a match available resources.

I'd like to write something that summarizes what the Scheduling & Eviction section contains, not what scheduling & eviction is. (I found this hard).

I am trying to come up (and work with your text) with a brief statement describing the following topic.
Readers will understand what content comes next.

More to crunch on:
Assigning taints and tolerations, scheduling resources, managing evictions

kbhawkey · 2020-06-24T14:07:55Z

@sftim , In the process of reviewing. This is more than a "tidy" up.
Generally, I like the descriptions as they work well with the docsy theme.

kbhawkey · 2020-06-24T16:01:57Z

content/en/docs/concepts/cluster-administration/_index.md

 description: >
  Lower-level detail relevant to creating or administering a Kubernetes cluster.
 ---

+<!-- overview -->
+The cluster administration overview is for anyone creating or administering a Kubernetes cluster.
+It assumes some familiarity with core Kubernetes [concepts](/docs/concepts/).


Is this a direct cut-n-paste from cluster-administration-overview?

Yep. I used mv then tweaked the metadata.

kbhawkey · 2020-06-24T16:09:13Z

content/en/docs/concepts/extend-kubernetes/_index.md

+
+*Configuration files* and *flags* are documented in the Reference section of the online documentation, under each binary:
+
+* [kubelet](/docs/admin/kubelet/)


I assume this is a direct copy.
nit: The links should be corrected (/docs/admin/).

kbhawkey · 2020-06-24T16:11:45Z

Example preview:
https://deploy-preview-21997--kubernetes-io-master-staging.netlify.app/docs/concepts/extend-kubernetes/

kbhawkey · 2020-06-24T16:59:23Z

Looking at the descriptions on the rendered page.
Some descriptions could be reduced, otherwise, I think the text distracts with the rest of the page. Such as:
https://deploy-preview-21997--kubernetes-io-master-staging.netlify.app/docs/concepts/services-networking/

The description for Workloads doesn't read as well to me, Understand Pods.
https://deploy-preview-21997--kubernetes-io-master-staging.netlify.app/docs/concepts/workloads/

sftim · 2020-06-24T17:59:29Z

@kbhawkey I agree there probably is better wording. What's in this PR is already the best suggestion I have though.

kbhawkey · 2020-06-24T20:23:53Z

@kbhawkey I agree there probably is better wording. What's in this PR is already the best suggestion I have though.

OK, I understand. Of note, the text appears in the page source meta data. Shorter strings seem better.
I think most of the descriptions work. I wonder if the problem (for me) is the placement of the
description on the page. The description appears first where as I would expect the title first and then the text snippet (functioning as an overview or synopsis). If the snippet is one sentence, it is not as noticeable. If more than one sentence, readers may not want to continue reading the rest of the page.
Could the page layout include the title and then the description?

sftim · 2020-06-24T20:31:56Z

Could the page layout include the title and then the description?

That means changing the Docsy theme, right? I'm not opposed to that but it seems like quite a chunk of work. We can do this right away, or at least sooner.

kbhawkey · 2020-06-24T20:34:00Z

I think the docs layout override of the theme could change:
website\layouts\docs\list.html

sftim · 2020-06-24T20:54:14Z

website/layouts/docs/list.html

Ah, yes!

kbhawkey · 2020-06-24T21:07:17Z

The theme default behavior lists the title first followed by the "lead" div.

kbhawkey · 2020-06-25T15:45:48Z

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

@@ -2,7 +2,6 @@
 title: "Configuration"
 weight: 80
 description: >
-  Kubernetes provides two similar resources for configuring Pods: ConfigMap and Secret. The main difference is
-  confidentiality; Secret lets you set up extra controls to keep the data in a Secret confidential.
+  Resouces that Kubernetes provides configuring Pods.


Resources that Kubernetes provides to configure Pods.

sftim · 2020-06-25T15:52:01Z

/retitle [WIP] Tidy concepts section post-Docsy

sftim · 2020-06-25T16:06:08Z

/retitle Tidy concepts section post-Docsy

Each section directly beneath Concepts gains a description.

Where an existing Concept section has an index and the first page is “Overview of X”, move the content of that overview into the index page itself. Also, configure redirects accordingly.

sftim · 2020-06-25T16:12:37Z

IMO this revised page is much better than the existing, inaccurate content - I'm keen to remove the misleading text:

The Kubernetes Master is a collection of three processes that run on a single node in your cluster, which is designated as the master node.

kbhawkey · 2020-06-27T23:15:50Z

@sftim, Things look good. I'd like to see this come together with the page structure change.
/lgtm

kbhawkey · 2020-06-27T23:28:34Z

Issue related to concepts section, #22110.

kbhawkey · 2020-06-28T00:11:02Z

/approve

k8s-ci-robot · 2020-06-28T00:11:25Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: kbhawkey

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:

~~OWNERS~~ [kbhawkey]

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

kbhawkey · 2020-06-28T00:22:59Z

@sftim, some of the pages look OK. Should have asked for a rebase to show the description updates on the pages.
The _index pages with page body content place the description after the page content instead of
before the content.
See, https://kubernetes.io/docs/concepts/containers/
https://kubernetes.io/docs/concepts/cluster-administration/
https://kubernetes.io/docs/concepts/extend-kubernetes/
https://kubernetes.io/docs/concepts/services-networking/

kbhawkey · 2020-06-28T01:04:30Z

Created a follow-up PR #22113.

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. language/en Issues or PRs related to English language labels Jun 22, 2020

k8s-ci-robot requested review from chenopis and thockin June 22, 2020 22:23

k8s-ci-robot added the sig/docs Categorizes an issue or PR as relevant to SIG Docs. label Jun 22, 2020

sftim force-pushed the 20200622_tidy_concepts_section_post_docsy branch 2 times, most recently from 31899f1 to 929269d Compare June 22, 2020 22:40

kbhawkey reviewed Jun 24, 2020

View reviewed changes

sftim force-pushed the 20200622_tidy_concepts_section_post_docsy branch from 929269d to 44db6c8 Compare June 24, 2020 13:27

kbhawkey reviewed Jun 24, 2020

View reviewed changes

sftim mentioned this pull request Jun 24, 2020

Move documentation page lead text after the heading #22046

Merged

sftim force-pushed the 20200622_tidy_concepts_section_post_docsy branch 2 times, most recently from 2de44fe to 5258f2c Compare June 25, 2020 15:43

kbhawkey reviewed Jun 25, 2020

View reviewed changes

k8s-ci-robot changed the title ~~Tidy concepts section post-Docsy~~ [WIP] Tidy concepts section post-Docsy Jun 25, 2020

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 Jun 25, 2020

sftim force-pushed the 20200622_tidy_concepts_section_post_docsy branch from 5258f2c to fa6e985 Compare June 25, 2020 16:05

k8s-ci-robot changed the title ~~[WIP] Tidy concepts section post-Docsy~~ Tidy concepts section post-Docsy Jun 25, 2020

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 Jun 25, 2020

sftim added 3 commits June 25, 2020 17:09

Add descriptions to Concept sections

3ff7312

Each section directly beneath Concepts gains a description.

Fold concept overview pages into section indexes

f265aed

Where an existing Concept section has an index and the first page is “Overview of X”, move the content of that overview into the index page itself. Also, configure redirects accordingly.

Switch note to use shortcode

4a4719d

sftim force-pushed the 20200622_tidy_concepts_section_post_docsy branch from fa6e985 to 4a4719d Compare June 25, 2020 16:11

k8s-ci-robot assigned kbhawkey Jun 27, 2020

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

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

k8s-ci-robot merged commit 86d373b into kubernetes:master Jun 28, 2020

kbhawkey mentioned this pull request Jun 28, 2020

adjust order of description and title, concept pages #22114

Closed

sftim deleted the 20200622_tidy_concepts_section_post_docsy branch October 16, 2020 13:57

Sea-n mentioned this pull request Jul 2, 2022

[de] sync content/de/docs/concepts/_index.md from upstream #33406

Closed

s-kawamura-w664 mentioned this pull request Aug 17, 2022

[ja] content/ja/docs/concepts/containers/overview.md is not needed. #36035

Closed

limck5856 mentioned this pull request Sep 18, 2024

3ff7312cff367e4321aedf6010bbb8b4a75b3163 #47992

Closed


		## Kubernetes Control Plane

		The various parts of the Kubernetes Control Plane, such as the Kubernetes Master and kubelet processes, govern how Kubernetes communicates with your cluster. The Control Plane maintains a record of all of the Kubernetes Objects in the system, and runs continuous control loops to manage those objects' state. At any given time, the Control Plane's control loops will respond to changes in the cluster and work to make the actual state of all the objects in the system match the desired state that you provided.


		Configuration files and flags are documented in the Reference section of the online documentation, under each binary:

		* [kubelet](/docs/admin/kubelet/)

Tidy concepts section post-Docsy #21997

Tidy concepts section post-Docsy #21997

Conversation

sftim commented Jun 22, 2020 • edited Loading

sftim commented Jun 22, 2020

sftim commented Jun 22, 2020

netlify bot commented Jun 22, 2020 • edited Loading

kbhawkey Jun 24, 2020 • edited Loading

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

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kbhawkey commented Jun 24, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kbhawkey commented Jun 24, 2020

kbhawkey commented Jun 24, 2020

sftim commented Jun 24, 2020

kbhawkey commented Jun 24, 2020 • edited Loading

sftim commented Jun 24, 2020

kbhawkey commented Jun 24, 2020

sftim commented Jun 24, 2020

kbhawkey commented Jun 24, 2020

Choose a reason for hiding this comment

sftim commented Jun 25, 2020

sftim commented Jun 25, 2020

sftim commented Jun 25, 2020

kbhawkey commented Jun 27, 2020

kbhawkey commented Jun 27, 2020

kbhawkey commented Jun 28, 2020

k8s-ci-robot commented Jun 28, 2020

kbhawkey commented Jun 28, 2020 • edited Loading

kbhawkey commented Jun 28, 2020

sftim commented Jun 22, 2020 •

edited

Loading

netlify bot commented Jun 22, 2020 •

edited

Loading

kbhawkey Jun 24, 2020 •

edited

Loading

kbhawkey commented Jun 24, 2020 •

edited

Loading

kbhawkey commented Jun 28, 2020 •

edited

Loading