diff --git a/doc/api/os.md b/doc/api/os.md
index 279ed1f18ddc0f..e89d1bf23267e0 100644
--- a/doc/api/os.md
+++ b/doc/api/os.md
@@ -140,6 +140,10 @@ The properties included on each object include:
 `nice` values are POSIX-only. On Windows, the `nice` values of all processors
 are always 0.
 
+`os.cpus().length` should not be used to calculate the amount of parallelism
+available to an application. Use
+[`os.availableParallelism()`](#osavailableparallelism) for this purpose.
+
 ## `os.devNull`
 
 <!-- YAML