Add fixing gitlab-shell to troubleshooting59248-docs-feedback-add-fixing-gitlab-shell-to-troubleshooting

- Fixed typo: commnicating => communicating
- Clarified on information about the token generation
- Removed line about restart gitlab, as it is not needed.

1 files changed, 14 insertions, 15 deletions

diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md
index 3c47ebee6e1..072bb208e62 100644
--- a/doc/administration/gitaly/index.md
+++ b/doc/administration/gitaly/index.md
@@ -353,28 +353,27 @@ When you attempt to perform commits and receive a 401 error, like this:
 
 ![401 Error](../img/gitaly/401_error.png)
 
-This means your Gitaly service is having issues commnicating with the
+This means your Gitaly service is having issues communicating with the
 gitlab-shell. To confirm this, you should run 
 `sudo /opt/gitlab/embedded/service/gitlab-shell/bin/check` on your
 Gitaly server. If it returns a 401 error when checking API access, you
-will need to check your gitlab-shell setup. A quick way to do this is
-to check the `/opt/gitlab/embedded/service/gitlab-rails/.gitlab_shell_secret`
+will need to check your gitlab-shell setup.
+
+A quick way to do this is to check the
+`/opt/gitlab/embedded/service/gitlab-rails/.gitlab_shell_secret`
 file on your application servers and your Gitaly server. They should
-match perfectly. If not, you would want to ensure the `secret_token`
-value for the `gitlab_shell` section of the `gitlab-secrets.json`
-file matches on all servers. 
+match perfectly. You can synchronize these in one of two ways:
+
+- Ensure the `secret_token` value for the `gitlab_shell` section of the `gitlab-secrets.json` file matches on all servers. 
+- Utilize the `gitlab_shell['secret_token']` setting in the `gitlab.rb` file for all server.
 
-You might also want to check the `gitlab.rb` file on your servers
-for the `gitlab_shell['secret_token']` settings. This allows for
-customizing the `secret_token` used by the gitlab-shell. If present,
-you would want to ensure both the application servers and the Gitaly
-server is using this setting as well in their corresponding 
-`gitlab.rb` files.
+Keep in mind that the `gitlab_shell['secret_token']` setting
+will override the `secret_token` value for the `gitlab_shell`
+section of the `gitlab-secrets.json` file.
 
-After changing this, make sure to reconfigure and restart GitLab on
-the server it was changed on:
+After synchronizing this, make sure to reconfigure GitLab on
+the server(s) it was changed on:
 
 ```sh
 sudo gitlab-ctl reconfigure
-sudo gitlab-ctl restart
 ```