diff --git a/doc/api/diagnostics_channel.md b/doc/api/diagnostics_channel.md
index d20337e443e485..fad4f2d069a32a 100644
--- a/doc/api/diagnostics_channel.md
+++ b/doc/api/diagnostics_channel.md
@@ -308,8 +308,11 @@ channel.publish({
 added:
  - v15.1.0
  - v14.17.0
+deprecated: REPLACEME
 -->
 
+> Stability: 0 - Deprecated: Use [`diagnostics_channel.subscribe(name, onMessage)`][]
+
 * `onMessage` {Function} The handler to receive channel messages
   * `message` {any} The message data
   * `name` {string|symbol} The name of the channel
@@ -344,6 +347,7 @@ channel.subscribe((message, name) => {
 added:
  - v15.1.0
  - v14.17.0
+deprecated: REPLACEME
 changes:
   - version:
     - v17.1.0
@@ -353,6 +357,8 @@ changes:
     description: Added return value. Added to channels without subscribers.
 -->
 
+> Stability: 0 - Deprecated: Use [`diagnostics_channel.unsubscribe(name, onMessage)`][]
+
 * `onMessage` {Function} The previous subscribed handler to remove
 * Returns: {boolean} `true` if the handler was found, `false` otherwise.
 
@@ -389,5 +395,6 @@ channel.unsubscribe(onMessage);
 
 [`'uncaughtException'`]: process.md#event-uncaughtexception
 [`channel.subscribe(onMessage)`]: #channelsubscribeonmessage
-[`diagnostics_channel.subscribe(name, onMessage)`]: #diagnostics_channelunsubscribename_onmessage
 [`diagnostics_channel.channel(name)`]: #diagnostics_channelchannelname
+[`diagnostics_channel.subscribe(name, onMessage)`]: #diagnostics_channelsubscribename-onmessage
+[`diagnostics_channel.unsubscribe(name, onMessage)`]: #diagnostics_channelunsubscribename-onmessage