diff --git a/docs/content/configuring-npm/package-lock-json.md b/docs/content/configuring-npm/package-lock-json.md
index c06540fb3ffae..4aa8dc375c89f 100644
--- a/docs/content/configuring-npm/package-lock-json.md
+++ b/docs/content/configuring-npm/package-lock-json.md
@@ -138,7 +138,8 @@ Package descriptors have the following fields:
   the case of packages fetched from the registry, this will be a url to a
   tarball.  In the case of git dependencies, this will be the full git url
   with commit sha.  In the case of link dependencies, this will be the
-  location of the link target.
+  location of the link target. `registry.npmjs.org` is a magic value meaning
+  "the currently configured registry".
 
 * integrity: A `sha512` or `sha1` [Standard Subresource
   Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/)
@@ -201,7 +202,8 @@ Dependency objects have the following fields:
 
 * resolved: For registry sources this is path of the tarball relative to
   the registry URL.  If the tarball URL isn't on the same server as the
-  registry URL then this is a complete URL.
+  registry URL then this is a complete URL. `registry.npmjs.org` is a magic
+  value meaning "the currently configured registry".
 
 * bundled:  If true, this is the bundled dependency and will be installed
   by the parent module.  When installing, this module will be extracted
diff --git a/docs/content/using-npm/registry.md b/docs/content/using-npm/registry.md
index 3b07ab11c5bdc..4a265db03f079 100644
--- a/docs/content/using-npm/registry.md
+++ b/docs/content/using-npm/registry.md
@@ -30,6 +30,13 @@ The registry URL used is determined by the scope of the package (see
 supplied by the `registry` config parameter.  See [`npm config`](/commands/npm-config),
 [`npmrc`](/configuring-npm/npmrc), and [`config`](/using-npm/config) for more on managing npm's configuration.
 
+When the default registry is used in a package-lock or shrinkwrap is has the
+special meaning of "the currently configured registry". If you create a lock
+file while using the default registry you can switch to another registry and
+npm will install packages from the new registry, but if you create a lock
+file while using a custom registry packages will be installed from that
+registry even after you change to another registry.
+
 ### Does npm send any information about me back to the registry?
 
 Yes.