Clarify the reasons for disabling writes

app/views/admin/application_settings/_form.html.haml

@@ -649,8 +649,9 @@
             By default, we write to the "authorized_keys" file to support old
             OpenSSH servers. If, and only if, you have configured the GitLab
             instance to use the AuthorizedKeysCommand, uncheck this to improve
-            performance.
-            = link_to icon('question-circle'), help_page_path('administration/operations/speed_up_ssh', anchor: 'tidying-up')
+            performance by preventing a sequential file read on each git SSH
+            access.
+            = link_to icon('question-circle'), help_page_path('administration/operations/speed_up_ssh', anchor: 'the-solution')
 
   - if Gitlab::Geo.license_allows?
     %fieldset

doc/administration/operations/speed_up_ssh.md

@@ -40,16 +40,22 @@ AuthorizedKeysCommand /opt/gitlab-shell/authorized_keys %u %k
 AuthorizedKeysCommandUser git
 ```
 
-Finally, reload the SSHD service:
+Reload the SSHD service:
 
 ```
 sudo service sshd reload
 ```
 
-## Tidying up
+Confirm that SSH is working by removing your user's SSH key in the UI, adding a new one, and attempting to pull a repo.
 
 > **Warning:** Do not disable writes until SSH is confirmed to be working perfectly because the file will quickly become out-of-date.
 
-You may disable any more writes to the `authorized_keys` file by unchecking `Write to "authorized_keys" file` in the Application Settings of your GitLab installation.
+In the case of lookup failures (which are not uncommon), the `authorized_keys` file will still be scanned. So git SSH performance will still be slow for many users as long as a large file exists.
+
+You can disable any more writes to the `authorized_keys` file by unchecking `Write to "authorized_keys" file` in the Application Settings of your GitLab installation.
 
 ![Write to authorized keys setting](img/write_to_authorized_keys_setting.png)
+
+Again, confirm that SSH is working by removing your user's SSH key in the UI, adding a new one, and attempting to pull a repo.
+
+Then you can backup and delete your `authorized_keys` file for best performance.