diff --git a/CHANGELOG.md b/CHANGELOG.md
index 03d983d..d2eb24a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,8 +1,8 @@
 # Changes
 
 * 2.6.next in progress
+  * Address [#531](https://github.com/seancorfield/honeysql/issues/531) and [#527](https://github.com/seancorfield/honeysql/issues/527) by adding tests and more documentation for `:composite`.
   * Address [#529](https://github.com/seancorfield/honeysql/issues/529) by fixing `:join` special syntax to support aliases and to handle expressions the same way `select` / `from` etc handle them (extra `[...]` nesting).
-  * Address [#527](https://github.com/seancorfield/honeysql/issues/527) by adding tests and more documentation for `:composite`.
   * Add example of mixed `DO UPDATE SET` with `EXCLUDED` and regular SQL expressions.
   * Improve exception message when un-`lift`-ed JSON expressions are used in the DSL.
   * Update Clojure versions (to 1.11.3 and 1.12.0-alpha12); update other dev/test dependencies.
diff --git a/doc/clause-reference.md b/doc/clause-reference.md
index 70f917e..23b6f9b 100644
--- a/doc/clause-reference.md
+++ b/doc/clause-reference.md
@@ -744,6 +744,17 @@ user=> (sql/format {:update :transport
  2]
 ```
 
+You can also `UPDATE .. FROM (VALUES ..) ..` where you might also need `:composite`:
+
+```clojure
+(sql/format {:update :table :set {:a :v.a}
+             :from [[{:values [[1 2 3]
+                               [4 5 6]]}
+                     [:v [:composite :a :b :c]]]]
+             :where [:and [:= :x :v.b] [:> :y :v.c]]})
+;;=> ["UPDATE table FROM (VALUES (?, ?, ?), (?, ?, ?)) AS v (a, b, c) SET a = v.a WHERE (x = v.b) AND (y > v.c)" 1 2 3 4 5 6]
+```
+
 ## delete, delete-from
 
 `:delete-from` is the simple use case here, accepting just a