diff --git a/docs/reference/gtk/migrating-3to4.xml b/docs/reference/gtk/migrating-3to4.xml
index 2ee41aac75..b97b8f128b 100644
--- a/docs/reference/gtk/migrating-3to4.xml
+++ b/docs/reference/gtk/migrating-3to4.xml
@@ -291,11 +291,16 @@
     </section>
 
     <section>
-      <title>Stop accessing GdkEvent fields</title>
+      <title>Adapt to GdkEvent API changes</title>
       <para>
-        Direct access to GdkEvent structs is no longer possible in GTK 4. Some
-        frequently-used fields already had accessors in GTK 3, and the remaining
-        fields have gained accessors in GTK 4.
+        Direct access to GdkEvent structs is no longer possible in 
+        GTK 4. Some frequently-used fields already had accessors
+        in GTK 3, and the remaining fields have gained accessors
+        in GTK 4.
+      </para>
+      <para>
+        GdkEvent is now a strictly read-only boxed type, and you
+        can no longer change any of its fields.
       </para>
     </section>
 
@@ -324,10 +329,51 @@
         GTK 4 no longer provides the gdk_device_grab() or gdk_seat_grab() apis.
       </para>
       <para>
-        If you need to dismiss a popup when the user clicks outside (a common
+        If you need to dismiss a popup when the user clicks outside (the most common
         use for grabs), you can use the GdkSurface #GdkSurface:autohide property instead.
         GtkPopover also has a #GtkPopover:autohide property.
       </para>
+      <para>
+        If you need to prevent the user from interacting with a window
+        while a dialog is open, use #GtkDialog::modal.
+      </para>
+    </section>
+
+    <section>
+      <title>Adapt to surface API changes</title>
+      <para>
+        In GTK 4, the two roles of a standalone toplevel window
+        and of a popup that is placed relative to a parent window
+        have been separated out into two interfaces, #GdkToplevel
+        and #GtkPopup.
+      </para>
+      <para>
+        Surfaces implementing these interfaces are created with
+        gdk_surface_new_toplevel() and gdk_surface_new_popup(),
+        respectively, and they are presented on screen using
+        gtk_toplevel_present() and gdk_popup_present(). The
+        present() functions take parameters in the form of an
+        auxiliary layout struct, #GdkPopupLayout or
+        #GdkToplevelLayout.
+      </para>
+      <para>
+        If your code is dealing directly with surfaces, you may
+        have to change it to call the API in these interfaces,
+        depending on whether the surface you are dealing with
+        is a toplevel or a popup.
+      </para>
+      <para>
+        As part of this reorganization, X11-only concepts such
+        as sticky or keep-below have been removed. If you need
+        to use them on your X11 windows, you will have to set
+        the corresponding X11 properties (as specified in the
+        EWMH) yourself.
+      </para>
+      <para>
+        A number of minor API cleanups have happened in GdkSurface
+        as well. For example, gdk_surface_input_shape_combine_region()
+        has been renamed to gdk_surface_set_input_region().
+      </para>
     </section>
 
     <section>
@@ -511,6 +557,14 @@
       </para>
     </section>
 
+    <section>
+      <title>Don't use -gtk-outline-...-radius in your CSS</title>
+      <para>
+        These non-standard properties have been removed from GTK
+        CSS. Just use regular border radius.
+      </para>
+    </section>
+
     <section>
       <title>Use gtk_widget_measure</title>
       <para>
@@ -947,6 +1001,19 @@
       </para>
     </section>
 
+    <section>
+      <title>Adapt to GtkIconTheme API changes</title>
+      <para>
+        gtk_icon_theme_lookup_icon() returns a #GtkIconPaintable
+        object now, instead of a #GtkIconInfo. It always returns
+        a paintable in the requested size, and never fails.
+      </para>
+      <para>
+        A number of no-longer-relevant lookup flags and API
+        variants have been removed.
+      </para>
+    </section>
+
     <section>
       <title>Update to GtkFileChooser API changes</title>
       <para>