Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve readability in persistent volume introduction #17176

Merged
merged 2 commits into from
Nov 5, 2019

Conversation

christophercarney
Copy link
Contributor

@christophercarney christophercarney commented Oct 24, 2019

Fixes #17174

Modify the wording around "compute" to adjust readability of the compute jargon term and make it clear it is a noun as opposed to a verb.

@k8s-ci-robot k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Oct 24, 2019
@k8s-ci-robot k8s-ci-robot added size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. language/en Issues or PRs related to English language sig/docs Categorizes an issue or PR as relevant to SIG Docs. labels Oct 24, 2019
@netlify
Copy link

netlify bot commented Oct 24, 2019

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

Built with commit 83a09b4

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

@sftim
Copy link
Contributor

sftim commented Oct 25, 2019

“compute” is jargon, meaning “the abstract concept of performing computation”. That's analogous to how the existing text has “storage” rather than “storage devices”.

Although “compute” is jargon, replacing it with “computers” doesn't feel right either: it changes the meaning. For examples of the jargon in common use, see https://aws.amazon.com/lambda/ and https://www.fastly.com/products/edge-compute.

@christophercarney can you suggest an alternative rewording that leaves the meaning and nuance intact?

@christophercarney
Copy link
Contributor Author

@sftim I see your point, but I believe that probably stems that "storage" is much more colloquial in technical jargon than "compute". Compute here reads awkwardly because used without some kind of qualifier it reads foremost as a verb. In your examples, the real jargon phrase would probably be "edge compute" and "compute time" rather than just "compute" alone. The qualifiers of time and edge add context to the word compute, giving it meaning.

In light of that, I'd then suggest adding some kind of qualifier to compute to make it clear that it is jargon rather than the verb. Brainstorming a couple of possibilities below:

compute resources
compute power (computing?)
compute problems
compute concepts
compute issues

@bradtopol
Copy link
Contributor

So it is very common in cloud computing for compute to be used as a noun. See
https://www.techopedia.com/definition/6580/compute

That being said, if you prefer changing compute to either "compute nodes" or "compute instances"
I would find both of those options as acceptable changes that improve readability. Computers is definitely not the proper change here.

/cc @zacharysarah @sftim
/assign

@christophercarney christophercarney changed the title Fix typo in persistent volume introduction Improve readability in persistent volume introduction Oct 26, 2019
@christophercarney
Copy link
Contributor Author

christophercarney commented Oct 26, 2019

I agree computer is wrong. I also agree compute is common as a noun in cloud computing but in this context the sentence reads a little strangely, especially to people who may be unfamiliar with cloud computing concepts. So I think adding the modifier to compute increases overall readability. Thanks for the feedback and discussion!

Copy link
Contributor

@sftim sftim left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No objection from me.

@christophercarney
Copy link
Contributor Author

/assign @bradtopol

Copy link
Contributor

@bradtopol bradtopol left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great job

@bradtopol
Copy link
Contributor

/lgtm
/approve

@k8s-ci-robot k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Nov 5, 2019
@k8s-ci-robot
Copy link
Contributor

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: bradtopol

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:

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

@k8s-ci-robot k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Nov 5, 2019
@k8s-ci-robot k8s-ci-robot merged commit a7a4f9d into kubernetes:master Nov 5, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
approved Indicates a PR has been approved by an approver from all required OWNERS files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. language/en Issues or PRs related to English language lgtm "Looks good to me", indicates that a PR is ready to be merged. sig/docs Categorizes an issue or PR as relevant to SIG Docs. size/XS Denotes a PR that changes 0-9 lines, ignoring generated files.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Issue with https://kubernetes.io/docs/concepts/storage/persistent-volumes/
4 participants