diff --git a/doc/api/http2.md b/doc/api/http2.md
index 1272b920522015..6e59e8147472f7 100644
--- a/doc/api/http2.md
+++ b/doc/api/http2.md
@@ -989,9 +989,6 @@ added: v8.4.0
     Defaults to `false`.
   * `parent` {number} Specifies the numeric identifier of a stream the newly
     created stream is dependent on.
-  * `weight` {number} Specifies the relative dependency of a stream in relation
-    to other streams with the same `parent`. The value is a number between `1`
-    and `256` (inclusive).
 * `callback` {Function} Callback that is called once the push stream has been
   initiated.
 * Returns: {undefined}
@@ -1012,6 +1009,10 @@ server.on('stream', (stream) => {
 });
 ```
 
+Setting the weight of a push stream is not allowed in the `HEADERS` frame. Pass
+a `weight` value to `http2stream.priority` with the `silent` option set to
+`true` to enable server-side bandwidth balancing between concurrent streams.
+
 #### http2stream.respond([headers[, options]])
 <!-- YAML
 added: v8.4.0