diff --git a/docs/reference/gtk/migrating-2to3.xml b/docs/reference/gtk/migrating-2to3.xml
index 64278b1fa0..34f4f92c32 100644
--- a/docs/reference/gtk/migrating-2to3.xml
+++ b/docs/reference/gtk/migrating-2to3.xml
@@ -119,6 +119,46 @@
     make CFLAGS+="-DGSEAL_ENABLE"
     </programlisting>
   </para>
+  <para>
+    While it may be painful to convert, this helps us keep API and ABI
+    compatibility when we change internal interfaces. As a quick example,
+    when adding GSEAL_ENABLE, if you see an error like:
+    <programlisting>
+    error: 'GtkToggleButton' has no member named 'active'
+    </programlisting>
+    this means that you are accessing the public structure of
+    GtkToggleButton directly, perhaps with some code like:
+    <informalexample><programlisting>
+      static void
+      on_toggled (GtkToggleButton *button)
+      {
+        if (button->active)
+          frob_active ();
+        else
+          frob_inactive ();
+      }
+    </programlisting></informalexample>
+  </para>
+  <para>
+    In most cases, this can easily be replaced with the correct accessor
+    method. The main rule is that if you have code like the above which
+    accesses the "active" field of a "GtkToggleButton", then the accessor
+    method becomes "gtk_toggle_button_get_active":
+    <informalexample><programlisting>
+      static void
+      on_toggled (GtkToggleButton *button)
+      {
+        if (gtk_toggle_button_get_active (button))
+          frob_active ();
+        else
+          frob_inactive ();
+      }
+    </programlisting></informalexample>
+  </para>
+  <para>
+    In the case of setting field members directly, there's usually
+    a corresponding setter method.
+  </para>
   </section>
 
   <section>