diff --git a/stdlib/Distributed/src/cluster.jl b/stdlib/Distributed/src/cluster.jl
index 28e4bf49b0fa69..af0a77ecf362d8 100644
--- a/stdlib/Distributed/src/cluster.jl
+++ b/stdlib/Distributed/src/cluster.jl
@@ -428,6 +428,10 @@ if istaskdone(t)   # Check if `addprocs` has completed to ensure `fetch` doesn't
     end
   end
 ```
+
+Only IDs of workers successfully launched and connected to are returned from a
+call to `addprocs`. Therefore it is always a good idea to check the return value
+and confirm if the requested number of processes were indeed added.
 """
 function addprocs(manager::ClusterManager; kwargs...)
     init_multi()