diff --git a/clients/src/main/java/org/apache/kafka/common/serialization/Deserializer.java b/clients/src/main/java/org/apache/kafka/common/serialization/Deserializer.java
index 9fd8d50be744d..ad8d2bfe4d4f6 100644
--- a/clients/src/main/java/org/apache/kafka/common/serialization/Deserializer.java
+++ b/clients/src/main/java/org/apache/kafka/common/serialization/Deserializer.java
@@ -63,7 +63,15 @@ default T deserialize(String topic, Headers headers, byte[] data) {
     }
 
     /**
-     * Deserialize a record value from a ByteBuffer into a value or object.
+     * Deserialize a record value from a {@link ByteBuffer} into a value or object.
+     *
+     * <p>If {@code ByteBufferDeserializer} is used by an application, the application code cannot make any assumptions
+     * about the returned {@link ByteBuffer} like the position, limit, capacity, etc., or if it is backed by
+     * {@link ByteBuffer#hasArray() an array or not}.
+     *
+     * <p>Similarly, if this method is overridden, the implementation cannot make any assumptions about the
+     * passed in {@link ByteBuffer} either.
+     *
      * @param topic topic associated with the data
      * @param headers headers associated with the record; may be empty.
      * @param data serialized ByteBuffer; may be null; implementations are recommended to handle null by returning a value or null rather than throwing an exception.
diff --git a/docs/upgrade.html b/docs/upgrade.html
index 24e2886822027..56efaffbd04a0 100644
--- a/docs/upgrade.html
+++ b/docs/upgrade.html
@@ -656,9 +656,9 @@ <h5><a id="upgrade_360_notable" href="#upgrade_360_notable">Notable changes in 3
         <li>The Apache Zookeeper dependency has been upgraded to 3.8.1 due to 3.6 reaching end-of-life. To bring both your
             Kafka and Zookeeper clusters to the latest versions:
             <ul>
-                <li><b>>=2.4</b> Kafka clusters can be updated directly.
+                <li><b>&gt;=2.4</b> Kafka clusters can be updated directly.
                     Zookeeper clusters which are running binaries bundled with Kafka versions 2.4 or above can be updated directly.</li>
-                <li><b><2.4</b> Kafka clusters first need to be updated to a version greater than 2.4 and smaller than 3.6.
+                <li><b>&lt;2.4</b> Kafka clusters first need to be updated to a version greater than 2.4 and smaller than 3.6.
                 Zookeeper clusters which are running binaries bundled with Kafka versions below 2.4 need to be updated to any
                 binaries bundled with Kafka versions greater than 2.4 and smaller than 3.6. You can then follow the first bullet-point.</li>
             </ul>
@@ -688,6 +688,10 @@ <h5><a id="upgrade_360_notable" href="#upgrade_360_notable">Notable changes in 3
             The configuration can also be updated dynamically and is applied to the broker. Workloads running on version 3.6.0 with compression can experience
             InvalidRecordExceptions and UnknownServerExceptions. Upgrading to 3.6.1 or newer or disabling the feature fixes the issue.
         </li>
+	<li>The <code>ByteBufferDeserializer</code> (<a href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=225152035">KIP-863</a>)
+	    was changed to avoid unnecessary deep-copies of data. This changes the behavior of the deserializer as user code cannot make any assumptions
+	    about buffer position, limit, capacity any longer.
+        </li>
     </ul>
 
 <h4><a id="upgrade_3_5_2" href="#upgrade_3_5_2">Upgrading to 3.5.2 from any version 0.8.x through 3.4.x</a></h4>