diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index 8bdf3c3e74f2a..2a978224c898e 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -965,6 +965,29 @@ To override `@npm/foo` to `1.0.0`, but only when it's a child of `@npm/bar@2.0.0
 }
 ```
 
+Versioned override keys do not just limit when nested overrides apply.
+They also replace the matched package with that version or range.
+In the example above, `@npm/bar@2.0.0` both matches `@npm/bar` at `2.0.0`
+and keeps `@npm/bar` on `2.0.0` while applying the nested `@npm/foo`
+override.
+
+If you want to keep the parent package on its existing spec while only
+overriding its children, set `"."` explicitly:
+
+```json
+{
+  "dependencies": {
+    "@npm/bar": "^2.0.0"
+  },
+  "overrides": {
+    "@npm/bar@2.0.0": {
+      ".": "$@npm/bar",
+      "@npm/foo": "1.0.0"
+    }
+  }
+}
+```
+
 You may not set an override for a package that you directly depend on unless both the dependency and the override itself share the exact same spec.
 To make this limitation easier to deal with, overrides may also be defined as a reference to a spec for a direct dependency by prefixing the name of the package you wish the version to match with a `$`.
 
@@ -979,9 +1002,15 @@ To make this limitation easier to deal with, overrides may also be defined as a
     // GOOD, specs match so override is allowed
     // "foo": "^1.0.0"
     // BEST, the override is defined as a reference to the dependency
-    "@npm/foo": "$foo",
+    // For scoped packages, use the full scoped name in the reference.
+    // BAD, will not resolve scoped package references.
+    // "@npm/foo": "$foo",
+    // "@npm/bar": "$bar",
+    // Use "$@npm/foo" instead of "$foo", and use "$@npm/bar" instead of "$bar".
+    // `$foo` and `$bar` are unscoped references and will not match scoped packages.
+    "@npm/foo": "$@npm/foo",
     // the referenced package does not need to match the overridden one
-    "@npm/bar": "$foo"
+    "@npm/bar": "$@npm/foo"
   }
 }
 ```