Document shell detection for tools and fix typos

1 files changed, 11 insertions, 6 deletions

diff --git a/doc/development/shell_scripting_guide/index.md b/doc/development/shell_scripting_guide/index.md
index 12ce14f2565..2a919ece4b0 100644
--- a/doc/development/shell_scripting_guide/index.md
+++ b/doc/development/shell_scripting_guide/index.md
@@ -41,7 +41,7 @@ that is:
 
 ## Shell language choice
 
-1. When you need to reduce the dependencies list, use what's provided by the environment.For example, for Docker images it's `sh` from `alpine` which is the base image for most of our tool images.
+1. When you need to reduce the dependencies list, use what's provided by the environment. For example, for Docker images it's `sh` from `alpine` which is the base image for most of our tool images.
 1. Everywhere else, use `bash` if possible. It's more powerful than `sh` but still a widespread shell.
 
 ## Code style and format
@@ -55,7 +55,7 @@ automate shell code formatting, checking for errors or vulnerabilities, etc.
 We're using the [ShellCheck](https://www.shellcheck.net/) utility in its default configuration to lint our
 shell scripts. 
 
-All projects with shell scripts should this GitLab CI/CD job:
+All projects with shell scripts should use this GitLab CI/CD job:
 
 ```yaml
 shell check:
@@ -64,10 +64,13 @@ shell check:
   before_script:
     - shellcheck --version
   script:
-    - shellcheck -s sh scripts/**/*.sh # path to your shell scripts
+    - shellcheck scripts/**/*.sh # path to your shell scripts
 ```
 
-Use `-s` flag to specify the shell dialect (`-s sh` or `-s bash`).
+TIP: **Tip:**
+By default, ShellCheck will use the [shell detection](https://github.com/koalaman/shellcheck/wiki/SC2148#rationale)
+to determine the shell dialect in use. If the shell file is out of your control and ShellCheck cannot
+detect the dialect, use `-s` flag to specify it: `-s sh` or `-s bash`.
 
 ### Formatting
 
@@ -76,11 +79,13 @@ We format shell scripts according to the [Google Shell Style Guide](https://goog
 so the following `shfmt` invocation should be applied to the project's script files:
 
 ```bash
-shfmt -i 2 -ci -ln posix scripts/**/*.sh
+shfmt -i 2 -ci scripts/**/*.sh
 ```
 
 TIP: **Tip:**
-Use `-ln` flag to specify the shell dialect (`-ln posix` or `-ln bash`).
+By default, shfmt will use the [shell detection](https://github.com/mvdan/sh#shfmt) similar to one of ShellCheck
+and ignore files starting with a period. To override this, use `-ln` flag to specify the shell dialect:
+`-ln posix` or `-ln bash`.
 
 NOTE: **Note:**
 Currently, the `shfmt` tool [is not shipped](https://github.com/mvdan/sh/issues/68) as a Docker image containing