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

[fokusferit]

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:

• "Just"
• "Easy / Easily / Simple"
• "Obviously / Clearly / Clear "
  ...

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:

• https://css-tricks.com/words-avoid-educational-writing/
• https://spin.atomicobject.com/2014/09/09/never-use-the-word-obviously/

Comments

[aimeeu]

@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]

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]

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]

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

• Incrementally. Starting with one subfolder of the docs, fixing step-by-step.

Also updating existing Guidelines for new Documentation.

[fokusferit]

/remove-lifecycle stale

[fejta-bot]

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]

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]

This issue has renewed importance with kubernetes/community#4884.

/remove-lifecycle rotten
/assign @celestehorgan

[celestehorgan]

/label wg-naming

[k8s-ci-robot]

@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:

/label wg-naming

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[celestehorgan]

/wg naming

[fejta-bot]

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]

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]

/unassign @celestehorgan
/assign @zacharysarah

[zacharysarah]

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]

@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:

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. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[k8s-ci-robot]

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

In response to this:

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. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[zacharysarah]

/priority important-longterm

[sftim]

/triage accepted

[geoffcline]

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]

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]

/remove-lifecycle stale

[celestehorgan]

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

[kbhawkey]

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

[kbhawkey]

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

[k8s-ci-robot]

@kbhawkey: Closing this issue.

In response to this:

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. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.