diff --git a/src/doc/src/reference/environment-variables.md b/src/doc/src/reference/environment-variables.md
index a10d7c8bf20..a630a5f58a5 100644
--- a/src/doc/src/reference/environment-variables.md
+++ b/src/doc/src/reference/environment-variables.md
@@ -253,6 +253,15 @@ let out_dir = env::var("OUT_DIR").unwrap();
                          current working directory of the build script when it
                          starts.
 * `CARGO_MANIFEST_LINKS` — the manifest `links` value.
+* `CARGO_MAKEFLAGS` — Contains parameters needed for Cargo's [jobserver]
+                      implementation to parallelize subprocesses.
+                      Rustc or cargo invocations from build.rs can already
+                      read `CARGO_MAKEFLAGS`, but GNU Make requires the
+                      flags to be specified either directly as arguments,
+                      or through the `MAKEFLAGS` environment variable.
+                      Currently Cargo doesn't set the `MAKEFLAGS` variable,
+                      but it's free for build scripts invoking GNU Make
+                      to set it to the contents of `CARGO_MAKEFLAGS`.
 * `CARGO_FEATURE_<name>` — For each activated feature of the package being
                            built, this environment variable will be present
                            where `<name>` is the name of the feature uppercased
@@ -288,10 +297,9 @@ let out_dir = env::var("OUT_DIR").unwrap();
                that care should be taken when interpreting this environment
                variable. For historical purposes this is still provided but
                recent versions of Cargo, for example, do not need to run `make
-               -j` as it'll automatically happen. Cargo implements its own
-               [jobserver] and will allow build scripts to inherit this
-               information, so programs compatible with GNU make jobservers will
-               already have appropriately configured parallelism.
+               -j`, and instead can set the `MAKEFLAGS` env var to the content
+               of `CARGO_MAKEFLAGS` to activate the use of Cargo's GNU Make
+               compatible [jobserver] for sub-make invocations.
 * `OPT_LEVEL`, `DEBUG` — values of the corresponding variables for the
                          profile currently being built.
 * `PROFILE` — `release` for release builds, `debug` for other builds.