[docs][glossary] Add page that lists all standardized k8s terms #5657

jesscodez · 2017-09-27T15:29:35Z

@chenopis This PR is a quick prototype of what we discussed last week. You mentioned that Sarah (or was it Paris?) thought it would be worth formally defining "user persona terms" like "cluster operator" and "application developer."

I put the link to this glossary page under Reference. You may have mentioned putting it on the home page--I think that categorically it makes sense under "Reference", but was that suggestion due to visibility concerns? If you feel strongly I can move it.

GIF of final product, illustrating all the random features:

This change is

k8sio-netlify-preview-bot · 2017-09-27T15:32:06Z

Deploy preview ready!

Built with commit ccc9a06

https://deploy-preview-5657--kubernetes-io-master-staging.netlify.com

jesscodez · 2017-09-27T15:37:36Z

See https://deploy-preview-5657--kubernetes-io-master-staging.netlify.com/docs/reference/glossary/

chenopis

Looks great!

As per our Slack convo:

I think we should simplify the title and just call it "Glossary".
We need to disable the "Edit this Page" button since changes requested by users would probably need to be made at the snippet level.
~~Don't worry about handling a long list of terms until we add more content. Then it will be worth a refactor.~~
The first incarnation of Glossary was in the Reference section, so I'm fine w/ leaving it there unless there is a huge uproar, which I doubt. It's easy enough to move if we need to.

chenopis · 2017-09-27T16:48:35Z

cc @parispittman

chenopis · 2017-09-27T16:50:48Z

@abiogenesis-now It was Paris (@parispittman) who mentioned adding community terms, but I like to think of it as coming from the uber-entity known as Saris. LOL

jesscodez · 2017-09-28T16:10:34Z

@chenopis addressed your comments! Do you think we can merge this first or should we keep it as a PR until we've fleshed out all the "People"/"User Persona" terms?

chenopis · 2017-09-28T17:45:45Z

@abiogenesis-now I want to merge this now, but since it's still pretty sparse, I think we should do a quick sprint to get maybe a dozen terms in before we merge.

EDIT: My suggestion would be to scrape terms from the top 25 "Related queries" in Google Trends for a discrete list of ones to start with.

jesscodez · 2017-09-28T18:21:47Z

@chenopis good idea! I'll make a list--might solicit help from you, Luke, and Jennifer to help populate/edit the definitions (if you have bandwidth, of course!)

chenopis · 2017-09-28T19:24:56Z

We can also scrape some terminology and/or definitions from: https://github.com/kubernetes-incubator/service-catalog/blob/master/terminology.md

jesscodez · 2017-09-29T00:22:06Z

Got carried away so I updated the glossary UI to be fancy and tag-filtering.
It might have bugs and not scale with a large number of terms (because essentially ALL content is being loaded onto the page and I'm using Javascript to hide/show things accordingly...maybe JS will be able to though, not sure).

TODOs:

~~add Paris's terms to the YAML~~
~~flesh out definitions~~
~~make sure tags make sense (and how we assigned things)~~
~~fix the CI test that checks canonical terms (since I changed the structure of those)~~
~~current setup kind of assumes that each term has at least one tag---I'll add that check to the CI test~~
~~probably also sort tags alphabetically~~
~~fix "Create an Issue" button~~

chenopis · 2017-10-03T22:32:37Z

FYI, Travis CI is failing

[0K$ go test -v k8s.io/kubernetes.github.io/test
=== RUN TestExampleObjectSchemas
--- PASS: TestExampleObjectSchemas (0.10s)
=== RUN TestReadme
--- PASS: TestReadme (0.01s)
=== RUN TestCanonicalTags
--- FAIL: TestCanonicalTags (0.00s)
glossary_test.go:43: Unable to read file ../_data/canonical-tags.yml: open ../_data/canonical-tags.yml: no such file or directory
FAIL
exit status 1
FAIL k8s.io/kubernetes.github.io/test 0.182s

chenopis · 2017-10-05T18:20:40Z

@abiogenesis-now For some reason, the "Create an Issue" button seems to have moved.

jesscodez · 2017-10-05T18:21:50Z

@chenopis good call, I'll add it to the TODOS

jesscodez · 2017-10-05T18:30:26Z

chenopis · 2017-10-05T21:59:31Z

@abiogenesis-now Can we change the spec and rename "formerly" to "aka"?

Additional Authors: * Andrew Chen <chenopis@users.noreply.github.com> * Steve Perry <steveperry-53@users.noreply.github.com>

jesscodez · 2017-10-06T22:08:21Z

Added GIF to main description (for reference)

chenopis · 2017-10-06T22:43:36Z

cc @jaredbhatti @devin-donnelly

thockin · 2017-10-07T04:09:53Z

_data/glossary/application-developer.yaml

+short-description: |
+  A person who writes an application that runs in a Kubernetes cluster.
+long-description: |
+  Typically an application developer works on one portion of an application that is split into microservices.


I don't think we need to say that microsrvices are "typical". Maybe "..one portion of an application, which might be monolithic or composed of many microservices."

Ok, I'll make the change.

thockin · 2017-10-07T04:11:27Z

_data/glossary/cluster-architect.yaml

+  A person who designs infrastructure that involves one or more Kubernetes clusters.
+
+long-description: |
+  They are concerned with distributed system best practices, such as high availability and security. A cluster architect is likely the one determining the suitability of a feature like cross-cloud cluster federation, for their particular setup.


I would strike references to federation.

Ok, I'll remove the second sentence.

thockin · 2017-10-07T04:12:17Z

_data/glossary/cluster.yaml

+short-description: |
+  A set of machines, called nodes, that run containerized applications managed by Kubernetes.
+long-description: |
+  Typically a cluster has serveral worker nodes and at least one master node.


typo: serveral

got it, thx

thockin · 2017-10-07T04:12:48Z

_data/glossary/code-contributor.yaml

+short-description: |
+  Develops and contributes code to the project that is part of the open source codebase.
+long-description: |
+  They are also an active community member and participate in one of the Special Interest Groups (SIGs).


"may participate"

"one or more"

thockin · 2017-10-07T04:14:36Z

_data/glossary/cronjob.yaml

+- core-object
+- workload
+short-description: |
+  Manages time based [Jobs](/docs/concepts/jobs/run-to-completion-finite-workloads/) that are run once or periodically on a given schedule.


"once" doesn't make sense "on a given schedule".

"A job that runs on a periodic schedule. "?

Ok, I'm going with "Manages a Job that runs on a periodic schedule."

thockin · 2017-10-07T04:18:26Z

_data/glossary/ingress.yaml

+- architecture
+- extension
+short-description: |
+  An API object that manages external access to the services in a cluster.


cluster, typically HTTP.

thockin · 2017-10-07T04:21:40Z

_data/glossary/kubernetes-api.yaml

+- fundamental
+- architecture
+short-description: |
+  The foundation for how Kubernetes represents and stores the state of the cluster.


This doesn't actually describe what an apiserver is.

"The application which serves the Kubernetes HTTP API, and which stores the state of the cluster".

I'm going with "The application which serves the Kubernetes HTTP API and stores the state of the cluster."

thockin · 2017-10-07T04:23:01Z

_data/glossary/maintainer.yaml

+tags:
+- community
+short-description: |
+  Works holistically across the project to maintain its health and success.


This is what they do, not what they are.

@abiogenesis-now Let's rewrite this.

How about...

short-description: "A highly experienced contributor, active in multiple areas, who has cross area ownership and GitHub repo write access."

long-description: "They work holistically across the project to maintain its health and success and have made substantial contributions, both through code development and broader organizational efforts."

works for me---I'm making the slight copyedit of saying "active in multiple areas [of Kubernetes]" but if you disagree, let me know

thockin · 2017-10-07T04:23:39Z

_data/glossary/pod.yaml

+- core-object
+- fundamental
+short-description: |
+  The smallest and simplest Kubernetes object. Represents a set of running processes on your cluster.


s/processes/containers ?

thockin · 2017-10-07T04:25:58Z

_data/glossary/service.yaml

+- fundamental
+- core-object
+short-description: |
+  An API object that manages load-balanced access to a replicated set of Pods.


An API object that describes how to access applications, such as a set of Pods, and can describe ports and load-balancers.

chenopis · 2017-10-09T16:21:37Z

BTW, we should double check the community membership role definitions against https://github.com/kubernetes/community/blob/master/community-membership.md.

zacharysarah

Editorial review, part 1. There's more to come; I'll pick back up tomorrow, beginning with Cluster Operators.

zacharysarah · 2017-10-09T22:23:35Z

_data/canonical-tags/fundamental.yaml

@@ -0,0 +1,3 @@
+id: fundamental
+name: Fundamental
+description: Relevant to a first-time user of Kubernetes.


Relevant for

zacharysarah · 2017-10-09T22:23:50Z

_data/canonical-tags/networking.yaml

@@ -0,0 +1,3 @@
+id: networking
+name: Networking
+description: Relevant to how Kubernetes components talk to each other (and to programs outside the cluster).


How Kubernetes components talk to each other and to programs outside the cluster.

👍 I'll be changing all of these as you suggested, but want to provide some context. Initially I prefaced a lot of these terms with "relevant to" because the description shows up as follows:

I wasn't sure if the description should directly apply to the tags themselves (in which case, it's clear that "relevant for" should be omitted), or to the terms described by the tags---so I initially opted for the latter.

Thanks for the context, it helps! 👍

zacharysarah · 2017-10-09T22:26:38Z

_data/canonical-tags/architecture.yaml

@@ -0,0 +1,3 @@
+id: architecture
+name: Architecture
+description: Related to the inner components of the Kubernetes system.


the Kubernetes system

Can we replace this with just "Kubernetes"? See operation.yaml for the same question. So:

description: The inner components of Kubernetes.

zacharysarah · 2017-10-09T22:27:59Z

_data/canonical-tags/operation.yaml

@@ -0,0 +1,3 @@
+id: operation
+name: Operation
+description: Relevant to starting and maintaining the Kubernetes system itself.


the Kubernetes system

Can we replace this with "Kubernetes"? See architecture.yaml for the same question. So:

description: Starting and maintaining Kubernetes.

zacharysarah · 2017-10-09T22:28:30Z

_data/canonical-tags/security.yaml

@@ -0,0 +1,3 @@
+id: security
+name: Security
+description: Relevant to keeping Kubernetes applications safe and secure.


description: Keeping Kubernetes applications safe and secure.

zacharysarah · 2017-10-09T22:54:56Z

_data/glossary/approver.yaml

+tags:
+- community
+short-description: |
+  Able to both review and approve K8s code contributions.


A person who can review and approve Kubernetes code contributions.

zacharysarah · 2017-10-09T22:56:09Z

_data/glossary/approver.yaml

+short-description: |
+  Able to both review and approve K8s code contributions.
+long-description: |
+  While code review is focused on code quality and correctness, approval is focused on holistic acceptance of a contribution including&#58; backwards/forwards compatibility, adhering to API and flag conventions, subtle performance and correctness issues, interactions with other parts of the system, etc.


While code review focuses on code quality and correctness, approval is focused on holistic acceptance of a contribution. Holistic acceptance includes backwards/forwards compatibility, adhering to API and flag conventions, subtle performance and correctness issues, interactions with other parts of the system, and others.

zacharysarah · 2017-10-09T22:57:03Z

_data/glossary/cla.yaml

+tags:
+- community
+short-description: |
+  Terms under which the contributor grants a license to the open source project for their contributions.


Terms under which a contributor grants a license to an open source project for their contributions.

zacharysarah · 2017-10-09T22:58:53Z

_data/glossary/cla.yaml

+short-description: |
+  Terms under which the contributor grants a license to the open source project for their contributions.
+long-description: |
+  They help enable a legal resolution to cases in which there are copyright disputes related to contributed material or intellectual property (IP).


CLAs help resolve legal disputes involving contributed material and intellectual property.

zacharysarah · 2017-10-09T23:00:08Z

_data/glossary/cluster-architect.yaml

+  A person who designs infrastructure that involves one or more Kubernetes clusters.
+
+long-description: |
+  They are concerned with distributed system best practices, such as high availability and security.


Cluster architects are concerned with best practices for distributed systems, for example: high availability and security.

zacharysarah

These look good. 🌟 Make sure to apply capitalization (or the lack thereof) of terms consistently across all entries. Pods/pods, Nodes/nodes, Clusters/clusters, etc.

zacharysarah · 2017-10-10T19:27:18Z

_data/glossary/cluster-operator.yaml

+tags:
+  - user-type
+short-description: |
+  A person who configures, controls, and monitors cluster(s).


zacharysarah · 2017-10-10T19:28:14Z

_data/glossary/cluster-operator.yaml

+
+long-description: |
+  Their primary responsibility is keeping the cluster up and running, which may involve periodic maintenance activities or upgrades.<br>
+  *(Cluster operators are not to be confused with the [Operator pattern](https://coreos.com/operators) that extends the Kubernetes API.)*


Note: Cluster operators are different from the Operator pattern that extends the Kubernetes API.

zacharysarah · 2017-10-10T19:29:01Z

_data/glossary/cluster.yaml

+short-description: |
+  A set of machines, called nodes, that run containerized applications managed by Kubernetes.
+long-description: |
+  Typically a cluster has several worker nodes and at least one master node.


A cluster has several worker nodes and at least one master node.

zacharysarah · 2017-10-10T19:30:09Z

_data/glossary/deployment.yaml

+short-description: |
+  An API object that manages a replicated application.
+long-description: |
+  Each replica is represented by a Pod, and the Pods are distributed among the Nodes of a cluster.


Make sure that Node is either capitalized or un-capitalized correctly for all entries; same for Pod.

👍 will stick to capitalizing standard K8s objects only

@abiogenesis-now Thanks, that was what I was trying to convey. 😸 👍

zacharysarah · 2017-10-10T19:31:17Z

_data/glossary/code-contributor.yaml

+- community
+- user-type
+short-description: |
+  Develops and contributes code to the project that is part of the open source codebase.


A person who develops and contributes code to the open source codebase.

zacharysarah · 2017-10-10T20:18:55Z

_data/glossary/statefulset.yml


 long-description: |
-  Like Deployments, StatefulSets manage Pods that are based on an identical container spec. However, although their specs are the same, the Pods in a StatefulSet are not interchangeable. Each Pod has a persistent identifier that it maintains across any rescheduling.
+  Like a Deployment, a StatefulSet manages Pods that are based on an identical container spec. Unlike a Deployment, a StatefulSet maintains a sticky identity for each of their Pods. These pods are created from the same spec, but are not interchangeable--each has a persistent identifier that it maintains across any rescheduling.


interchangeable: each has

zacharysarah · 2017-10-10T20:35:29Z

_data/glossary/upstream.yaml

+short-description: |
+  May refer to: core Kubernetes or the source repo from which a repo was forked.
+long-description: |
+  In the Kubernetes Community, conversations often use *upstream* to mean the core Kubernetes codebase, which the general ecosystem, other code, or third-party tools rely upon. For example, community members may suggest that a feature is moved upstream so that it is in the core codebase instead of in a plugin or third-party tool.


relies upon.

zacharysarah · 2017-10-10T20:35:40Z

_data/glossary/wg.yaml

@@ -0,0 +1,9 @@
+id: wg
+name: WG (Working Group)


working group

zacharysarah · 2017-10-10T20:36:33Z

_data/glossary/wg.yaml

+short-description: |
+  Facilitates the discussion and/or implementation of a short-lived, narrow, or decoupled project for a committee, SIG, or cross-SIG effort.
+long-description: |
+  They are a way of organizing people to accomplish a discrete task and are relatively easy to create and deprecate when inactive.


Working groups are a way of organizing people to accomplish a discrete task, and are relatively easy to create and deprecate when inactive.

zacharysarah · 2017-10-10T20:36:41Z

_data/glossary/wg.yaml

+  Facilitates the discussion and/or implementation of a short-lived, narrow, or decoupled project for a committee, SIG, or cross-SIG effort.
+long-description: |
+  They are a way of organizing people to accomplish a discrete task and are relatively easy to create and deprecate when inactive.
+  For more information, see the [kubernetes/community](https://github.com/kubernetes/community) repo and the current list of [SIGs and Working Groups](https://github.com/kubernetes/community/blob/master/sig-list.md).


working groups

jesscodez · 2017-10-11T17:25:53Z

Addressed most of your comments @zacharysarah and added some more cross-linking. Also am now using long-description: > rather than long-description: | in some of the YAML files because this allows you to break up your text semantically (without actually resulting in rendered linebreaks).

…multiparagraph definitions.

chenopis

/lgtm

zacharysarah

LGTM! 🌟 🌟

jesscodez added the team/heptio label Sep 27, 2017

jesscodez requested a review from chenopis September 27, 2017 15:29

k8s-ci-robot added 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 Sep 27, 2017

k8s-github-robot assigned Bradamant3 Sep 27, 2017

chenopis reviewed Sep 27, 2017

View reviewed changes

chenopis added the Docs Review: Open Issues label Sep 27, 2017

chenopis added this to the Glossary milestone Sep 27, 2017

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Sep 28, 2017

chenopis added Docs LGTM labels Oct 6, 2017

Add comprehensive glossary page

32c4bc0

Additional Authors: * Andrew Chen <chenopis@users.noreply.github.com> * Steve Perry <steveperry-53@users.noreply.github.com>

chenopis assigned steveperry-53 Oct 6, 2017

thockin reviewed Oct 7, 2017

View reviewed changes

incorporate Tim's feedback

ce9a271

chenopis added Tech Review: Open Issues and removed Needs Tech Review labels Oct 9, 2017

chenopis requested a review from zacharysarah October 9, 2017 18:57

chenopis added Docs Review: Open Issues and removed Docs LGTM labels Oct 9, 2017

zacharysarah suggested changes Oct 9, 2017

View reviewed changes

address zach's comments

f3eec70

zacharysarah suggested changes Oct 10, 2017

View reviewed changes

Jessica Yao added 2 commits October 11, 2017 10:00

address more comments

fd50322

add additional crosslinking

bd7f8c0

Add platform developer, tweak formatting for disambiguation cases or …

ccc9a06

…multiparagraph definitions.

chenopis removed the Tech Review: Open Issues label Oct 12, 2017

k8s-ci-robot assigned chenopis Oct 12, 2017

k8s-ci-robot added the lgtm label Oct 12, 2017

chenopis approved these changes Oct 12, 2017

View reviewed changes

zacharysarah approved these changes Oct 12, 2017

View reviewed changes

zacharysarah added Docs LGTM and removed Docs Review: Open Issues labels Oct 12, 2017

zacharysarah merged commit b22947a into kubernetes:master Oct 12, 2017

jesscodez mentioned this pull request Oct 18, 2017

[docs] Introduce custom Jekyll tags for better glossary integration #5954

Merged

[docs][glossary] Add page that lists all standardized k8s terms #5657

[docs][glossary] Add page that lists all standardized k8s terms #5657

Uh oh!

Conversation

jesscodez commented Sep 27, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

k8sio-netlify-preview-bot commented Sep 27, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jesscodez commented Sep 27, 2017

Uh oh!

chenopis left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chenopis commented Sep 27, 2017

Uh oh!

chenopis commented Sep 27, 2017

Uh oh!

jesscodez commented Sep 28, 2017

Uh oh!

chenopis commented Sep 28, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jesscodez commented Sep 28, 2017

Uh oh!

chenopis commented Sep 28, 2017

Uh oh!

jesscodez commented Sep 29, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chenopis commented Oct 3, 2017

Uh oh!

chenopis commented Oct 5, 2017

Uh oh!

jesscodez commented Oct 5, 2017

Uh oh!

jesscodez commented Oct 5, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chenopis commented Oct 5, 2017

Uh oh!

jesscodez commented Oct 6, 2017

Uh oh!

chenopis commented Oct 6, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

jesscodez commented Sep 27, 2017 •

edited

Loading

k8sio-netlify-preview-bot commented Sep 27, 2017 •

edited

Loading

chenopis left a comment •

edited

Loading

chenopis commented Sep 28, 2017 •

edited

Loading

jesscodez commented Sep 29, 2017 •

edited

Loading

jesscodez commented Oct 5, 2017 •

edited

Loading