Clarify kubectl shell autocompletion documentation (#13060)

* Clarify kubectl autocompletion documentation (#12405)

* Clarify kubectl autocompletion documentation (#12405)

Remove comments.

* Clarify kubectl autocompletion documentation

Fix according to review.

* Clarify kubectl autocompletion documentation

Use selectable tabs.

* Fix note callouts in various sections

* Clarify kubectl autocompletion documentation

Change wording of intro paragraph.

content/en/docs/tasks/tools/install-kubectl.md

@@ -110,9 +110,7 @@ If you are on Windows and using [Powershell Gallery](https://www.powershellgalle
     install-kubectl.ps1 [-DownloadLocation <path>]
     ```
 
-    {{< note >}}
-    If you do not specify a `DownloadLocation`, `kubectl` will be installed in the user's temp Directory.
-    {{< /note >}}
+    {{< note >}}If you do not specify a `DownloadLocation`, `kubectl` will be installed in the user's temp Directory.{{< /note >}}
 
     The installer creates `$HOME/.kube` and instructs it to create a config file
 
@@ -122,9 +120,7 @@ If you are on Windows and using [Powershell Gallery](https://www.powershellgalle
     kubectl version
     ```
 
-    {{< note >}}
-    Updating the installation is performed by rerunning the two commands listed in step 1.
-    {{< /note >}}
+    {{< note >}}Updating the installation is performed by rerunning the two commands listed in step 1.{{< /note >}}
 
 ## Install on Windows using Chocolatey or scoop
 
@@ -170,9 +166,7 @@ To install kubectl on Windows you can use either [Chocolatey](https://chocolatey
     New-Item config -type file
     ```
 
-    {{< note >}}
-    Edit the config file with a text editor of your choice, such as Notepad.
-    {{< /note >}}
+    {{< note >}}Edit the config file with a text editor of your choice, such as Notepad.{{< /note >}}
 
 ## Download as part of the Google Cloud SDK
 
@@ -295,63 +289,139 @@ kubectl cluster-info dump
 
 ## Enabling shell autocompletion
 
-kubectl includes autocompletion support, which can save a lot of typing!
+kubectl provides autocompletion support for Bash and Zsh, which can save you a lot of typing!
 
-The completion script itself is generated by kubectl, so you typically just need to invoke it from your profile.
+Below are the procedures to set up autocompletion for Bash (including the difference between Linux and macOS) and Zsh.
 
-Common examples are provided here. For more details, consult `kubectl completion -h`.
+{{< tabs name="kubectl_autocompletion" >}}
 
-### On Linux, using bash
-On CentOS Linux, you may need to install the bash-completion package which is not installed by default.
+{{% tab name="Bash on Linux" %}}
 
-```shell
-yum install bash-completion -y
-```
+### Introduction
+
+The kubectl completion script for Bash can be generated with the command `kubectl completion bash`. Sourcing the completion script in your shell enables kubectl autocompletion.
+
+However, the completion script depends on [**bash-completion**](https://github.com/scop/bash-completion), which means that you have to install this software first (you can test if you have bash-completion already installed by running `type _init_completion`).
+
+### Install bash-completion
+
+bash-completion is provided by many package managers (see [here](https://github.com/scop/bash-completion#installation)). You can install it with `apt-get install bash-completion` or `yum install bash-completion`, etc.
 
-To add kubectl autocompletion to your current shell, run `source <(kubectl completion bash)`.
+The above commands create `/usr/share/bash-completion/bash_completion`, which is the main script of bash-completion. Depending on your package manager, you have to manually source this file in your `~/.bashrc` file.
 
-To add kubectl autocompletion to your profile, so it is automatically loaded in future shells run:
+To find out, reload your shell and run `type _init_completion`. If the command succeeds, you're already set, otherwise add the following to your `~/.bashrc` file:
 
 ```shell
-echo "source <(kubectl completion bash)" >> ~/.bashrc
+source /usr/share/bash-completion/bash_completion
 ```
 
-### On macOS, using bash
-On macOS, you will need to install bash-completion support via [Homebrew](https://brew.sh/) first:
+Reload your shell and verify that bash-completion is correctly installed by typing `type _init_completion`.
+
+### Enable kubectl autocompletion
+
+You now need to ensure that the kubectl completion script gets sourced in all your shell sessions. There are two ways in which you can do this:
+
+- Source the completion script in your `~/.bashrc` file:
+
+    ```shell
+    echo 'source <(kubectl completion bash)' >>~/.bashrc
+    ```
+
+- Add the completion script to the `/etc/bash_completion.d` directory:
+
+    ```shell
+    kubectl completion bash >/etc/bash_completion.d/kubectl
+    ```
+
+{{< note >}}
+bash-completion sources all completion scripts in `/etc/bash_completion.d`.
+{{< /note >}}
+
+Both approaches are equivalent. After reloading your shell, kubectl autocompletion should be working.
+
+{{% /tab %}}
+
+
+{{% tab name="Bash on macOS" %}}
+
+{{< warning>}}
+macOS includes Bash 3.2 by default. The kubectl completion script requires Bash 4.1+ and doesn't work with Bash 3.2. A possible way around this is to install a newer version of Bash on macOS (see instructions [here](https://itnext.io/upgrading-bash-on-macos-7138bd1066ba)). The below instructions only work if you are using Bash 4.1+.
+{{< /warning >}}
+
+### Introduction
+
+The kubectl completion script for Bash can be generated with the command `kubectl completion bash`. Sourcing the completion script in your shell enables kubectl autocompletion.
+
+However, the completion script depends on [**bash-completion**](https://github.com/scop/bash-completion), which means that you have to install this software first (you can test if you have bash-completion already installed by running `type _init_completion`).
+
+### Install bash-completion
+
+You can install bash-completion with Homebrew:
 
 ```shell
-## If running Bash 3.2 included with macOS
-brew install bash-completion
-## or, if running Bash 4.1+
 brew install bash-completion@2
 ```
 
-Follow the "caveats" section of brew's output to add the appropriate bash completion path to your local .bashrc.
+{{< note >}}
+The `@2` stands for bash-completion 2, which is required by the kubectl completion script (it doesn't work with bash-completion 1). In turn, bash-completion 2 requires Bash 4.1+, that's why you needed to upgrade Bash.
+{{< /note >}}
 
-If you installed kubectl using the [Homebrew instructions](#install-with-homebrew-on-macos) then kubectl completion should start working immediately.
-
-If you have installed kubectl manually, you need to add kubectl autocompletion to the bash-completion:
+As stated in the output of `brew install` ("Caveats" section), add the following lines to your `~/.bashrc` or `~/.bash_profile` file:
 
 ```shell
-kubectl completion bash > $(brew --prefix)/etc/bash_completion.d/kubectl
+export BASH_COMPLETION_COMPAT_DIR=/usr/local/etc/bash_completion.d
+[[ -r /usr/local/etc/profile.d/bash_completion.sh ]] && . /usr/local/etc/profile.d/bash_completion.sh
 ```
 
-The Homebrew project is independent from Kubernetes, so the bash-completion packages are not guaranteed to work.
+Reload your shell and verify that bash-completion is correctly installed by typing `type _init_completion`.
+
+### Enable kubectl autocompletion
+
+You now need to ensure that the kubectl completion script gets sourced in all your shell sessions. There are multiple ways in which you can do this:
 
-### Using Zsh
-If you are using zsh edit the ~/.zshrc file and add the following code to enable kubectl autocompletion:
+- Source the completion script in your `~/.bashrc` file:
+
+    ```shell
+    echo 'source <(kubectl completion bash)' >>~/.bashrc
+
+    ```
+
+- Add the completion script to `/usr/local/etc/bash_completion.d`:
+
+    ```shell
+    kubectl completion bash >/usr/local/etc/bash_completion.d/kubectl
+    ```
+
+- If you installed kubectl with Homebrew (as explained [here](#install-with-homebrew-on-macos)), then the completion script was automatically installed to `/usr/local/etc/bash_completion.d/kubectl`. In that case, you don't need to do anything.
+
+{{< note >}}
+bash-completion (if installed with Homebrew) sources all the completion scripts in the directory that is set in the `BASH_COMPLETION_COMPAT_DIR` environment variable.
+{{< /note >}}
+
+All approaches are equivalent. After reloading your shell, kubectl autocompletion should be working.
+{{% /tab %}}
+
+{{% tab name="Zsh" %}}
+
+The kubectl completion script for Zsh can be generated with the command `kubectl completion zsh`. Sourcing the completion script in your shell enables kubectl autocompletion.
+
+To do so in all your shell sessions, add the following to your `~/.zshrc` file:
 
 ```shell
-if [ $commands[kubectl] ]; then
-  source <(kubectl completion zsh)
-fi
+source <(kubectl completion zsh)
 ```
 
-Or when using [Oh-My-Zsh](http://ohmyz.sh/), edit the ~/.zshrc file and update the `plugins=` line to include the kubectl plugin.
+After reloading your shell, kubectl autocompletion should be working.
+
+If you get an error like `complete:13: command not found: compdef`, then add the following to the beginning of your `~/.zshrc` file:
 
 ```shell
-plugins=(kubectl)
+autoload -Uz compinit
+compinit
 ```
+{{% /tab %}}
+{{< /tabs >}}
+
 {{% /capture %}}
 
 {{% capture whatsnext %}}