Clarify Rugged with Puma details

doc/administration/gitaly/index.md

@@ -988,9 +988,12 @@ When GitLab calls a function that has a "Rugged patch", it performs two checks:
 - Is the feature flag for this patch set in the database? If so, the feature flag setting controls
   GitLab's use of "Rugged patch" code.
 - If the feature flag is not set, GitLab tries accessing the filesystem underneath the
-  Gitaly server directly. If it can, it will use the "Rugged patch".
+  Gitaly server directly. If it can, it will use the "Rugged patch":
+  - If using Unicorn.
+  - If using Puma and [thread count](../../install/requirements.md#puma-threads) is set
+    to `1`.
 
-The result of both of these checks is cached.
+The result of these checks is cached.
 
 To see if GitLab can access the repository filesystem directly, we use the following heuristic:
 

doc/administration/nfs.md

@@ -127,7 +127,9 @@ administrators to keep NFS server delegation disabled.
 
 ### Improving NFS performance with GitLab
 
-#### Improving NFS performance with Unicorn
+NFS performance with GitLab can in some cases be improved with
+[direct Git access](gitaly/index.md#direct-access-to-git-in-gitlab) using
+[Rugged](https://github.com/libgit2/rugged).
 
 NOTE: **Note:**
 From GitLab 12.1, it will automatically be detected if Rugged can and should be used per storage.
@@ -138,18 +140,16 @@ If you previously enabled Rugged using the feature flag, you will need to unset
 sudo gitlab-rake gitlab:features:unset_rugged
 ```
 
-If the Rugged feature flag is explicitly set to either true or false, GitLab will use the value explicitly set.
+If the Rugged feature flag is explicitly set to either `true` or `false`, GitLab will use the value explicitly set.
 
 #### Improving NFS performance with Puma
 
 NOTE: **Note:**
-From GitLab 12.7, Rugged auto-detection is disabled if Puma thread count is greater than 1.
+From GitLab 12.7, Rugged is not automatically enabled if Puma thread count is greater than `1`.
 
-If you want to use Rugged with Puma, it is recommended to [set Puma thread count to 1](https://docs.gitlab.com/omnibus/settings/puma.html#puma-settings).
+If you want to use Rugged with Puma, [set Puma thread count to `1`](https://docs.gitlab.com/omnibus/settings/puma.html#puma-settings).
 
-If you want to use Rugged with Puma thread count more than 1, Rugged can be enabled using the [feature flag](../development/gitaly.md#legacy-rugged-code)
-
-If the Rugged feature flag is explicitly set to either true or false, GitLab will use the value explicitly set.
+If you want to use Rugged with Puma thread count more than `1`, Rugged can be enabled using the [feature flag](../development/gitaly.md#legacy-rugged-code).
 
 ## NFS client
 

doc/administration/operations/puma.md

@@ -36,7 +36,8 @@ For deployments where NFS is used to store Git repository, we allow GitLab to us
 [Rugged](https://github.com/libgit2/rugged).
 
 Rugged usage is automatically enabled if direct Git access
-[is available](../gitaly/index.md#how-it-works), unless it is disabled by
+[is available](../gitaly/index.md#how-it-works)
+and Puma is running single threaded, unless it is disabled by
 [feature flags](../../development/gitaly.md#legacy-rugged-code).
 
 MRI Ruby uses a GVL. This allows MRI Ruby to be multi-threaded, but running at
@@ -49,7 +50,7 @@ We are actively working on removing Rugged usage. Even though performance withou
 is acceptable today, in some cases it might be still beneficial to run with it.
 
 Given the caveat of running Rugged with multi-threaded Puma, and acceptable
-performance of Gitaly, we are disabling Rugged usage if Puma multi-threaded is
+performance of Gitaly, we disable Rugged usage if Puma multi-threaded is
 used (when Puma is configured to run with more than one thread).
 
 This default behavior may not be the optimal configuration in some situations. If Rugged

doc/install/requirements.md

@@ -183,7 +183,7 @@ optimal settings for your infrastructure.
 ### Puma threads
 
 The recommended number of threads is dependent on several factors, including total memory, and use
-of [legacy Rugged code](../development/gitaly.md#legacy-rugged-code).
+of [legacy Rugged code](../administration/gitaly/index.md#direct-access-to-git-in-gitlab).
 
 - If the operating system has a maximum 2 GB of memory, the recommended number of threads is `1`.
   A higher value will result in excess swapping, and decrease performance.