search

kubernetes / website

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

Remove insensitive wordings from the docs like just - easy or - simple #17070

Closed fokusferit closed 3 years ago

fokusferit commented 5 years ago

This is a Feature Request

My feature request is about leveling up the documentation text and wording to be less insensitive and inconsiderate language.

There are great tools out there these days, like alexjs which makes it possible to catch phrases like "Just", "easy" or "simple".

Using alexjs also shows certain words which are common to kubernetes domain, e.g. host.

It allows us to challenge certain narratives which are used to be normal, also accepted terminology but should be challenged in order to increase inclusivity. When I started learning kubernetes (or any other technology) often reading "just simple do X" when I didn't know what that simple task means, created a barrier in my mind that I don't understand the topic.

An example is the `contribute/start.md" page, where alexjs returns this:

start.md
      42:28-42:35  warning  `Special` may be insensitive, use `Has a disability`, `Person with a disability`, `People with disabilities` instead  special       retext-equality
     126:3-126:10  warning  `Clearly` may be insensitive, try not to use it                                                                       clearly       retext-equality
    135:68-135:72  warning  Reconsider using `suck`, it may be profane                                                                            suck          retext-profanities
    180:50-180:54  warning  `just` may be insensitive, try not to use it                                                                          just          retext-equality
    298:47-298:53  warning  `fellow` may be insensitive, use `person`, `friend`, `pal`, `folk`, `individual` instead                              gal-guy       retext-equality
    301:14-301:20  warning  `simple` may be insensitive, try not to use it                                                                        simple

What would you like to be added

I would like to improve all these wordings, step by step, starting with english and contribute folder or the concepts folder first.

Removing in particular words like:

I'm aware that alexjs (or retext-js) warns about more words, yet changing "deep-dive" or "host" isn't possible without reducing clearness.

Why is this needed

Some blogs to make a point:

Comments

aimeeu commented 5 years ago

@fokusferit - thanks for your excellent feedback! I have to find out if SIG Docs can add a tool like this. In the meantime, would you like to open a PR to update the start.md page?

/sig docs /kind feature /priority backlog

christophercarney commented 5 years ago

I'm seeing a lot of these words like "basically", "obviously", "simply", etc. in two main places other than the docs: blog posts and case studies. Obviously ;) editing these out of the docs is the main focus of this story but editing these words out of blog posts as well could make sense and increases readability. I'm under the general impression that most adverbs usually serve no purpose but to fill space anyways.

Case studies, on the other hand, are a bit more nuanced because many of these words come in the form of direct quotes. In these cases I believe editing these words out would be inappropriate. Thoughts?

Second thing, some of these words are systemic. Perfect example: "easy" and "easily". Searching easily comes up with 17 pages of references. Some of these references are valid, some are not. What would be the most appropriate way to break up this into reasonable PRs?

fejta-bot commented 4 years ago

Issues go stale after 90d of inactivity. Mark the issue as fresh with /remove-lifecycle stale. Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta. /lifecycle stale

fokusferit commented 4 years ago

As I didn't had time to really start working on this, the best way is like how we do it in software development:

Also updating existing Guidelines for new Documentation.

fokusferit commented 4 years ago

/remove-lifecycle stale

fejta-bot commented 4 years ago

Issues go stale after 90d of inactivity. Mark the issue as fresh with /remove-lifecycle stale. Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta. /lifecycle stale

fejta-bot commented 4 years ago

Stale issues rot after 30d of inactivity. Mark the issue as fresh with /remove-lifecycle rotten. Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta. /lifecycle rotten

zacharysarah commented 4 years ago

This issue has renewed importance with https://github.com/kubernetes/community/pull/4884.

/remove-lifecycle rotten /assign @celestehorgan

celestehorgan commented 4 years ago

/label wg-naming

k8s-ci-robot commented 4 years ago

@celestehorgan: The label(s) /label wg-naming cannot be applied. These labels are supported: api-review, community/discussion, community/maintenance, community/question, cuj/build-train-deploy, cuj/multi-user, platform/aws, platform/azure, platform/gcp, platform/minikube, platform/other, tide/merge-method-merge, tide/merge-method-rebase, tide/merge-method-squash

In response to [this](https://github.com/kubernetes/website/issues/17070#issuecomment-652697982): >/label wg-naming Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.
celestehorgan commented 4 years ago

/wg naming

fejta-bot commented 4 years ago

Issues go stale after 90d of inactivity. Mark the issue as fresh with /remove-lifecycle stale. Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta. /lifecycle stale

fejta-bot commented 4 years ago

Stale issues rot after 30d of inactivity. Mark the issue as fresh with /remove-lifecycle rotten. Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta. /lifecycle rotten

justaugustus commented 4 years ago

/remove-lifecycle rotten

justaugustus commented 4 years ago

/unassign @celestehorgan /assign @zacharysarah

zacharysarah commented 4 years ago

After review from WG Naming, this issue is actionable and ready for contributor help.

From a SIG Docs standpoint, this would also make a good first issue (albeit a large one).

/triage important-long-term /good-first-issue /help-wanted

k8s-ci-robot commented 4 years ago

@zacharysarah: This request has been marked as suitable for new contributors.

Please ensure the request meets the requirements listed here.

If this request no longer meets these requirements, the label can be removed by commenting with the /remove-good-first-issue command.

In response to [this](https://github.com/kubernetes/website/issues/17070): >After review from WG Naming, this issue is actionable and ready for contributor help. > >From a SIG Docs standpoint, this would also make a good first issue (albeit a large one). > >/triage important-long-term >/good-first-issue >/help-wanted Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.
k8s-ci-robot commented 4 years ago

@zacharysarah: The label(s) triage/important-long-term cannot be applied, because the repository doesn't have them

In response to [this](https://github.com/kubernetes/website/issues/17070#issuecomment-722043286): >After review from WG Naming, this issue is actionable and ready for contributor help. > >From a SIG Docs standpoint, this would also make a good first issue (albeit a large one). > >/triage important-long-term >/good-first-issue >/help-wanted Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.
zacharysarah commented 4 years ago

/priority important-longterm

sftim commented 4 years ago

/triage accepted

geoffcline commented 4 years ago

I'm working on a draft addition to the kubernetes style guide that encourages reviewing drafts for inclusive language before submitting a PR, and includes instructions on running alexjs.

fejta-bot commented 3 years ago

Issues go stale after 90d of inactivity. Mark the issue as fresh with /remove-lifecycle stale. Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-contributor-experience at kubernetes/community. /lifecycle stale

sftim commented 3 years ago

/remove-lifecycle stale

celestehorgan commented 3 years ago

@kbhawkey – are you intending to do any more work on this, or can we close the issue?

kbhawkey commented 3 years ago

Hi @celestehorgan . No, I think I covered most of the cases mentioned in this issue. Thanks!

kbhawkey commented 3 years ago

I plan to close this issue. If there is more work to do, you can reopen. Thanks! /close

k8s-ci-robot commented 3 years ago

@kbhawkey: Closing this issue.

In response to [this](https://github.com/kubernetes/website/issues/17070#issuecomment-822908098): >I plan to close this issue. >If there is more work to do, you can reopen. >Thanks! >/close Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.