diff --git a/README.md b/README.md
index a24ac629..bce27d56 100644
--- a/README.md
+++ b/README.md
@@ -163,9 +163,9 @@ Compressing the vectors with product quantization is done as follows:
                                                                  16, // number of subspaces
                                                                  256, // number of centroids per subspace
                                                                  true); // center the dataset
-            ByteSequence<?>[] compressed = pq.encodeAll(ravv);
+            // Note: before jvector 3.1.0, encodeAll returned an array of ByteSequence.
+            PQVectors pqv = pq.encodeAll(ravv);
             // write the compressed vectors to disk
-            PQVectors pqv = new PQVectors(pq, compressed);
             pqv.write(out);
         }
 ```
diff --git a/UPGRADING.md b/UPGRADING.md
index d935f86a..1e61221f 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -1,3 +1,17 @@
+# Upgrading from 3.0.x to 3.1.x
+
+## Critical API changes
+
+- `VectorCompressor.encodeAll()` now returns a `CompressedVectors` object instead of a `ByteSequence<?>[]`.
+  This provides better encapsulation of the compression functionality while also allowing for more efficient
+  creation of the `CompressedVectors` object.
+- The `ByteSequence` interface now includes an `offset()` method to provide offset information for the sequence.
+  any time the method `ByteSequence::get` is called, the full backing data is returned, and as such, the `offset()`
+  method is necessary to determine the offset of the data in the backing array.
+- `PQVectors` constructor has been updated to support immutable instances and explicit chunking parameters.
+- The `VectorCompressor.createCompressedVectors(Object[])` method is now deprecated in favor of the new API that returns
+  `CompressedVectors` directly from `encodeAll()`.
+
 # Upgrading from 2.0.x to 3.0.x
 
 ## Critical API changes