diff --git a/packages/docusaurus/static/configuration/yarnrc.json b/packages/docusaurus/static/configuration/yarnrc.json
index 2e61080cb9b8..7c0e38d0bf3d 100644
--- a/packages/docusaurus/static/configuration/yarnrc.json
+++ b/packages/docusaurus/static/configuration/yarnrc.json
@@ -82,7 +82,7 @@
       "_package": "@yarnpkg/core",
       "type": ["number", "string"],
       "title": "Compression level employed for zip archives",
-      "description": "Possible values go from 0 (\"no compression, faster\") to 9 (\"heavy compression, slower\"). The default is 'mixed', which is a variant of 9 where files may be stored uncompressed if the builtin libzip heuristic thinks it will lead to a more sensible result.",
+      "description": "Possible values go from `0` (\"no compression, faster\") to `9` (\"heavy compression, slower\"). The value `mixed` is a variant of `9` where files are stored uncompressed if the gzip overhead would exceed the size gain.\n\nThe default is `0`, which tends to be significantly faster to install. Projects using zero-installs are advised to keep it this way, as experiments showed that Git stores uncompressed package archives more efficiently than gzip-compressed ones.",
       "enum": ["mixed", 0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
       "default": "mixed"
     },